idMatchApi.yml

openapi: 3.0.0
info:
  version: 1.1.0
  title: ID Match API
  description: 

ID Match API Specification from Internet2 Trust and Identity, and Spherical Cow Group

security:
  - accessCode:
      - read
      - write
servers:
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/I2_TrustAndIdentity/ID_Match/1.0.0

paths:
  /sis:

    get:
      description: Returns a list of people
      parameters:
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: Successfully returned a list of people
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/corePerson'
        '400':
          $ref: '#/components/responses/400Error'

    post:
      description: Get a reference ID for an SoR person
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/corePerson'
      responses:
        '200':
          description: Found (or added) person record
        '400':
          $ref: '#/components/responses/400Error'

  /sis/{sorId}:
    get:
      description: Obtain information about an person from his or her sorId
      parameters:
      - name: sorId
        in: path
        required: true
        schema:
          type: string

      responses:
        '200':
          description: Successfully returned the requested person record
          content:
            application/json:
              schema:
                type: object
                properties:
                  artist_name:
                    type: string
                  artist_genre:
                    type: string
                  albums_recorded:
                    type: integer

        '400':
          $ref: '#/components/responses/400Error'
  /example:
    get:
      summary: Server example operation
      description: >-
        This is an example operation to show how security is applied to the
        call.
      responses:
        '200':
          description: OK
  /ping:
    get:
      summary: Server heartbeat operation
      description: >-
        This operation shows how to override the global security defined above,
        as we want to open it up for all users.
      security: []
      responses:
        '200':
          description: OK

components:
  securitySchemes:
    accessCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'http://example.com/oauth/auth'
          tokenUrl: 'http://example.com/oauth/token'
          scopes:
            write: allows modifying resources
            read: allows reading resources

  schemas:
    corePerson:
      required:
        - sorId
      type: object
      properties:
        sorId:
          type: integer
        dateOfBirth:
          type: string
        names:
          type: array
          items:
            type: object
            properties:
              nameType:
                type: string
              givenName:
                type: string
              familyName:
                type: string
  parameters:
    PageLimit:
      name: limit
      in: query
      description: Limits the number of items on a page
      schema:
        type: integer

    PageOffset:
      name: offset
      in: query
      description: Specifies the page number of the artists to be displayed
      schema:
        type: integer

  responses:
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string