diff --git a/id-match-api-2021-02-10.yml b/id-match-api-2021-02-10.yml new file mode 100644 index 0000000..ef49755 --- /dev/null +++ b/id-match-api-2021-02-10.yml @@ -0,0 +1,450 @@ +openapi: 3.0.0 +info: + version: 1.2.2 + title: ID Match API + description: ID Match API Specification from Internet2 Trust and Identity, and Spherical Cow Group + +security: + - accessCode: + - read + - write +servers: + - url: https://virtserver.swaggerhub.com/I2/idMatch/v1 + description: "SwaggerHub API Auto Mocking" + +paths: + /people/{sorLabel}/{sorId}: + + post: + tags: + - idMatch + summary: POST-based; Search only, similar to a regular request, except that a new identity will never be created as a result of the request + operationId: requestSerchOnlyPost + parameters: + - name: sorLabel + in: path + description: The official designation of the requesting SOR + required: true + schema: + type: string + - name: sorId + in: path + description: The SOR-assigned identifier for the person + required: true + schema: + type: string + + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + responses: + '201': + description: Return new referenceId for a person new to ID Match + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + referenceId: M523441767 + + '200': + description: Return referenceId for a person known to ID Match + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + referenceId: M523441767 + + '300': + description: Multiple Choices + content: + application/json: + schema: + $ref: '#/components/schemas/candidateMatches' + example: + matchRequest: '1009' + candidates: + - confidence: '85' + referenceId: M219488003 + explanation: Family name exact match, given name initial match + attributes: + - sor: HRMS + identifiers: + - type: sor + identifier: 089010023 + - type: network + identifier: pl292 + names: + - type: official + given: Patricia + family: Lee + ou: Biomedical Informatics + - sor: Alumni + identifiers: + - type: sor + identifier: A330-200 + - type: network + identifier: pl292 + names: + - type: official + given: Patricia + family: Lee + ou: Class of 1997 + identifiers: + - type: network + identifier: pl292 + - type: enterprise + identifier: '905008772' + - confidence: '71' + referenceId: M523441767 + attributes: + - sor: guest + identifiers: + - type: sor + identifier: pl388 + - type: network + identifier: pl388 + names: + - type: official + given: Patricia + family: Lee + telephoneNumbers: + - type: mobile + number: '8185551234' + identifiers: + - type: network + identifier: pl388 + - type: enterprise + identifier: '905003148' + - referenceId: new + attributes: + - sor: SIS + identifiers: + - type: sor + identifier: '971194843' + names: + - type: official + given: Pat + family: Lee + telephoneNumbers: + - type: mobile + number: '8185551234' + + '202': + description: Accepted. Candidates sent for manual resolution + content: + application/json: + schema: + type: object + properties: + matchRequest: + type: string + description: Optionally returns a matchRequest ID for this pending case + example: + matchRequest: 1009 + + '400': + $ref: '#/components/responses/400Error' + + put: + tags: + - idMatch + summary: Request a Reference Identifier for an SOR Person + operationId: requestRefId + parameters: + - name: sorLabel + in: path + description: The official designation of the requesting SOR + required: true + schema: + type: string + - name: sorId + in: path + description: The SOR-assigned identifier for the person + required: true + schema: + type: string + + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + + responses: + '201': + description: Return new referenceId for a person new to ID Match + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + referenceId: M523441767 + + '200': + description: Return referenceId for a person known to ID Match + content: + application/json: + schema: + $ref: '#/components/schemas/people' + example: + names: + - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + referenceId: M523441767 + + + '400': + $ref: '#/components/responses/400Error' + + /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: + people: + type: object + properties: + sorLabel: + type: string + sorId: + type: string + dateOfBirth: + type: string + names: + type: array + items: + type: object + properties: + type: + type: string + given: + type: string + family: + type: string + address: + type: array + items: + type: object + properties: + country: + type: string + formatted: + type: string + language: + type: string + locality: + type: string + postalCode: + type: string + region: + type: string + room: + type: string + streetAddress: + type: string + type: + type: string + verified: + type: string + emailAddress: + type: array + items: + type: object + properties: + address: + type: string + type: + type: string + verified: + type: string + identifier: + type: array + items: + type: object + properties: + id: + type: string + type: + type: string + primaryAffiliation: + type: string + gender: + type: string + telephoneNumber: + type: array + items: + type: object + properties: + number: + type: string + type: + type: string + referenceId: + type: string + + candidateMatches: + type: object + properties: + matchRequest: + type: string + candidates: + type: array + items: + type: object + properties: + confidence: + type: integer + referenceId: + type: string + explanation: + type: string + description: optional; rationale for including this candidate + attributes: + type: array + items: + type: object + properties: + schema: + $ref: '#/components/schemas/people' + identifiers: + type: array + items: + type: object + properties: + type: + type: string + identifier: + 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 + diff --git a/id-match-api.yml b/id-match-api.yml index ef49755..b8257b2 100644 --- a/id-match-api.yml +++ b/id-match-api.yml @@ -9,7 +9,7 @@ security: - read - write servers: - - url: https://virtserver.swaggerhub.com/I2/idMatch/v1 + - url: https://virtserver.swaggerhub.com/I2/api/idMatch/v1 description: "SwaggerHub API Auto Mocking" paths: @@ -194,9 +194,9 @@ paths: put: tags: - - idMatch - summary: Request a Reference Identifier for an SOR Person - operationId: requestRefId + - idMatch Reconciliation + summary: Forced reconciliation (when presented with multiple candidates, this is the operation to specify which candidate to select) + operationId: forcedReconciliation parameters: - name: sorLabel in: path @@ -215,26 +215,46 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/people' + $ref: '#/components/schemas/candidateMatches' + example: - names: - - - type: official - given: Pat - family: Lee - dateOfBirth: "1983-03-18" - identifiers: - - - type: national - identifier: 3B902AE12DF55196 - telephoneNumbers: - - - type: mobile - number: 8185551234 + matchRequest: '1009' + candidates: + - confidence: '85' + referenceId: M219488003 + explanation: Family name exact match, given name initial match + attributes: + - sor: HRMS + identifiers: + - type: sor + identifier: 089010023 + - type: network + identifier: pl292 + names: + - type: official + given: Patricia + family: Lee + ou: Biomedical Informatics + - sor: Alumni + identifiers: + - type: sor + identifier: A330-200 + - type: network + identifier: pl292 + names: + - type: official + given: Patricia + family: Lee + ou: Class of 1997 + identifiers: + - type: network + identifier: pl292 + - type: enterprise + identifier: '905008772' responses: - '201': - description: Return new referenceId for a person new to ID Match + '200': + description: Return referenceId for the person indicated in the reconciliation request content: application/json: schema: @@ -256,8 +276,8 @@ paths: number: 8185551234 referenceId: M523441767 - '200': - description: Return referenceId for a person known to ID Match + '201': + description: Return referenceId for the new person specified in the reconciliation request content: application/json: schema: @@ -279,10 +299,10 @@ paths: number: 8185551234 referenceId: M523441767 - '400': $ref: '#/components/responses/400Error' - + '409': + $ref: '#/components/responses/409Error' /ping: get: summary: Server heartbeat operation @@ -447,4 +467,12 @@ components: properties: message: type: string - + 409Error: + description: A forced reconciliation request is being attempted using out of date information + content: + application/json: + schema: + type: object + properties: + message: + type: string