swagger.yaml

swagger: '2.0'

#####################################################################
#                              API Information                      #
#####################################################################
info:
  title: ISSN-L Resolver
  version: "1.0.3"

  description: |
    Validate ISSN's and ISSN-L's, and converts any ISSN to the correspondent (canonic) ISSN-L.
    
    **ISSN** is a standard public [opaque identifier](https://en.wikipedia.org/wiki/Unique_identifier) for [journals](https://en.wikipedia.org/wiki/Periodical_publication), assigned by the [ISSN-ORG authority](http://www.issn.org). Its main function is to be a short alias for the [systematic name](https://en.wikipedia.org/wiki/Systematic_name) of the journal, uniquely identifying the publication content (*ISSN-L*) or a specific [media type](https://en.wikipedia.org/wiki/Media_(communication)) of the publication. In the latter case, for example, the same journal can have an *eletronic-ISSN* and a *print-ISSN*, which identifies its electronic and printed publications separately.
    
    The **ISSN-L resolver** converts any ISSN to its corresponding [ISSN-L](https://en.wikipedia.org/wiki/ISSN#Linking_ISSN) ("Linking ISSN") using a lightweight SQL structure.

  contact:
    email: peter@ok.org.br

  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

tags:
- name: checkers
  description: Check format and/or existence of the string input. 
- name: int-checkers
  description: Check format and/or existence of the integer input.
- name: converters
  description: Converts string input name to que requested output name. 
- name: int-converters
  description: Converts integer input name to que requested output name. 
- name: metadata-retriev
  description: basic information (metadata) retrieval by string input. 
- name: int-metadata-retriev
  description: basic information (metadata) retrieval by integer input. 

parameters:
  issn:
    name: issn
    in: path
    description: commom ISSN code. 
    required: true
    type: string
    pattern: ^\d{4}-\d{3}[\dxX]$
  issn7:
    name: issn7
    in: path
    description: the first 7 digits of the ISSN code. 
    required: true
    type: integer
    format: int32
    minimum: 1
    maximum: 9999999

definitions:
  ArrayOfInt:
    type: array
    items:
      type: integer

  ArrayOfStr:
    type: array
    items:
      type: string

#####################################################################
#                              PATHS                                #
#####################################################################
paths:

  /{issn}/isC:
    get:
      tags:
      - checkers
      summary: Check that input is an ISSN-L.
      operationId: isC-str
      description: |
        Check that input is a Linking ISSN (an ISSN-L). The error 404 needs an updated database, to be an real "ISSN not exists". 
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: boolean
        404:
          description: has not found the input issn.
        416:
          description: issn format is invalid.
          
  /{issn}/isN:
    get:
      tags:
      - checkers
      summary: Check that input is an ISSN (existis in the database).
      operationId: isN-str
      description: |
        Check that the Name (ISSN) exists, returning true. When input is out of range returns null, else the boolean false indicates "not found".
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: boolean
        404:
          description: has not found the requested issn.
        416:
          description: issn out of range (null, 0 or big)


  /int/{issn7}/isC:
    get:
      tags:
      - int-checkers
      summary: Check that input is an ISSN-L.
      operationId: isC-int
      description: |
        Check that input is a Linking ISSN (an ISSN-L). The error 404 needs an updated database, to be an real "ISSN not exists". 
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn7'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: boolean
        404:
          description: has not found the requested issn.
        416:
          description: issn out of range (null, 0 or big)

  /int/{issn7}/isN:
    get:
      tags:
      - int-checkers
      summary: Check that input is an ISSN (existis in the database).
      operationId: isN-int
      description: |
        Check that the Name (ISSN) exists, returning true. When input is out of range returns null, else the boolean false indicates "not found".
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn7'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: boolean
        404:
          description: has not found the requested issn.
        416:
          description: issn out of range (null, 0 or big)


  /{issn}/N2C:
    get:
      tags:
      - converters
      summary: Converts input ISSN code into its ISSN-L.
      operationId: N2C-str
      description: |
        Converts commom ISSN input into a corresponding Linking ISSN (an ISSN-L).
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: string
        404:
          description: has not found the input issn.
        416:
          description: issn format is invalid.
          
  /{issn}/N2Ns:
    get:
      tags:
      - converters
      summary: Converts input ISSN code into a set of ISSNs grouped by its ISSN-L.
      operationId: N2Ns-str
      description: |
        Converts commom ISSN input into a corresponding "grouped by ISSN-L" set of ISSNs.
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn'
      responses:
        200:
          description: search results matching criteria
          schema:
            $ref: "#/definitions/ArrayOfStr"
        404:
          description: has not found the input issn.
        416:
          description: issn format is invalid.

  /int/{issn7}/N2C:
    get:
      tags:
      - int-converters
      summary: Converts integer input into its ISSN-L.
      operationId: N2C-int
      description: |
        Converts Converts integer input (representing an ISSN code) into a corresponding Linking ISSN (an ISSN-L).
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn7'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: integer
        404:
          description: has not found the input issn.
        416:
          description: issn format is invalid.
          
  /int/{issn7}/N2Ns:
    get:
      tags:
      - int-converters
      summary: Converts integer input into all set of ISSNs grouped by its ISSN-L.
      operationId: N2Ns-int
      description: |
        Converts Converts integer input (representing an ISSN code) into a corresponding "group by ISSN-L" set of ISSNs.
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn7'
      responses:
        200:
          description: search results matching criteria
          schema:
            $ref: "#/definitions/ArrayOfInt"
        404:
          description: has not found the input issn.
        416:
          description: issn format is invalid.

  /info:
    get:
      tags:
      - full
      summary: show metadata about current ISSN database.
      operationId: infoDB
      description: |
        Information about ISSN database. Not use REST status codes.
      produces:
        - application/json
        - application/xml
      responses:
        200:
          description: retrieve information
          schema:
            type: object

  /{issn}/info:
    get:
      tags:
      - full
      summary: When input exist, returns all basic metadata about it.
      operationId: info
      description: |
        Supply all basic metadata about input and, when not exist, explain in a error message. Not use REST status codes.
      produces:
        - application/json
        - application/xml
      parameters:
      - $ref: '#/parameters/issn'
      responses:
        200:
          description: retrieve information
          schema:
            type: object


# Added by API Auto Mocking Plugin
host: api.ok.org.br
basePath: /issn
schemes:
 - http
 - https