# WIPO Pearl API
#
swagger: '2.0'
info:
  title: REST API for WIPO Pearl
  description: REST API for WIPO Pearl terminology database  https://wipopearl.wipo.int/en/linguistic
  version: "1.0.0"
# the domain of the service
host: api.wipopearl.pct.prd.web1.wipo.int
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
consumes:
  - application/json  
produces:
  - application/json

securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: x-api-key
    in: header


paths:
  /records:
    get:
      summary: Searches for terms in WIPO Pearl database records 
      security:
        - ApiKeyAuth: []
      description: |
        Searches for terms in WIPO Pearl database records; each database record treats a single specific concept and contains terms designating that concept in a minimum of 2 languages and a maximum of 10 
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: term
          in: query
          required: true
          description:  a designation that represents a concept in a specific subject field and language; there can be more than one term per concept in a given language, if a term has synonyms
          type: string
        - name: sourceLanguages
          type: string
          in: query
          required: false
          description: the comma-separated ISO 639-1 source language, in which the searched term can be in AR, DE, EN, ES, FR, JA, KO, PT,  RU, ZH
        - name: targetLanguages
          type: string
          in: query
          required: false
          description: the comma-separated ISO 639-1 target language, in which equivalents for the searched term can be found in AR, DE, EN, ES, FR, JA, KO, PT, RU, ZH
        - name: subjectFields
          type: string
          in: query
          required: false
          description: the subject fields selected for the search (empty means all), comprising ADMN, AERO, AGRI, AUDV, BLDG, CHEM, DATA, ELEC, ENGY, ENVR, FOOD, HOME, HORO, LEGL, MANU, MARI, MEAS, MECH, MEDI, METL, MILI, MINE, PACK, PRNT, RAIL, ROAD, SCIE, SPRT, TEXT
        - name: abbreviation
          in: query
          type: boolean
          required: false
          description: searches only for abbreviations
        - name: exactSearch
          in: query
          type: boolean
          required: false
          description: searches only for exact matches  of the searched term
        - name: limit
          in: query
          type: integer
          required: false
          description: controls the number of records to be retrieved per page; the default limit is 5          
        - name: offset
          type: integer
          in: query
          required: false
          description: controls the starting point of the response and indicates which pages to retrieve; the default offset is 0
        - name: count
          type: integer
          in: query
          required: false
          description: maximum number of records to be retrieved       

      tags:
        - Available services
      responses:
        200:
          description: Records containing the searched terms in the requested languages 
          headers:
            Access-Control-Allow-Origin:
              type: "string"
          schema:
            $ref: '#/definitions/Records'
        400:
          description: Bad request
          headers:
            Access-Control-Allow-Origin:
              type: "string"
          schema:
            $ref: '#/definitions/Error'
        415:
          description: Unsupported Media type
          headers:
            Access-Control-Allow-Origin:
              type: "string"       

      x-amazon-apigateway-integration:
        type: mock
        requestTemplates:
          application/json: |
            {
              "statusCode" : 200
            }
        responses:
          default:
            statusCode: "200"
            responseParameters:
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,X-Amz-Date,Authorization,X-Api-Key'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
            responseTemplates:
              application/json: |
                {}

  /records/{id}:
    get:
      summary: Searches for terms by record id
      security:
        - ApiKeyAuth: []      
      description: |
        Retrieves the full database record in which a term appears 
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          type: string
          required: true
          description: id of the database record that contains the full details for the searched term  
        - name: langCode
          in: query
          type: string
          required: false
          description: ISO 639-1 language code AR, DE, EN, ES, FR, JA, KO, PT, RU, ZH
      tags:
        - Available services
      responses:
        200:
          description: ok
          headers:
            Access-Control-Allow-Origin:
              type: "string"
          schema:
            $ref: '#/definitions/Record'
        400:
          description: Bad request
          headers:
            Access-Control-Allow-Origin:
              type: "string"
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not Found
          headers:
            Access-Control-Allow-Origin:
              type: "string"
          schema:
            $ref: '#/definitions/NotFound'
        415:
          description: Unsupported Media type
          headers:
            Access-Control-Allow-Origin:
              type: "string"    
              
definitions: 
  Records:
    properties:
      hits: 
        type: integer
      code: 
        type: integer
      maxPages: 
        type: integer
      count: 
        type: integer
      limit:
        type: integer
      offset:
        type: integer
      terms: 
        type: array
        items: 
          type: object
          properties: 
            id: 
              description: the record id to be used in order to retrieve the full database record
              type: integer
              format: int32
            term: 
              type: string
            subjectField: 
              type: string
            pageno: 
              type: integer
              format: int32

  Record: 
    type: array
    description: contains a minimum of 2 languageItems and a maximum of 10
    items: 
      type: object
      properties: 
        subjectField: 
          type: object
          properties: 
            code: 
              type: string
            description: 
              type: string
            id: 
              type: string
            sdlid: 
              type: string
        languageItems: 
          type: array
          description: this object contains 1 or more termItems per language
          items: 
            type: object
            properties: 
              language: 
                type: string
              id: 
                type: string
              termItems: 
                type: array
                items: 
                  type: object
                  description: this object contains the term found plus other data elements associated with that term as recorded in the WIPO Pearl database
                  properties: 
                    id: 
                      type: string
                    clir: 
                      type: boolean
                    searchUrl: 
                      type: string
                    term: 
                      type: string
                    expertKey: 
                      type: string
                    recordtermId: 
                      type: string
                    rating: 
                      type: string
                    context: 
                      type: string
                    usage: 
                      type: string
                    sourceLink: 
                      type: string
                    sourceText: 
                      type: string
  
  NotFound:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string

  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  

