diff --git a/README.adoc b/README.adoc index ddcd0d3..59085ec 100644 --- a/README.adoc +++ b/README.adoc @@ -18,6 +18,6 @@ Editor: {Editor}, {Email} ==== Partial Specification for ID Match API -link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-1.2.yml[YAML mapping of ID Match API Specification 1.2.2] + +link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.yml[YAML mapping of ID Match API Specification 1.2.2] + link:id-match-spec.adoc[ID Match API Specification in asciidoc] + link:https://spaces.at.internet2.edu/display/cifer/SOR-Registry+Strawman+ID+Match+API[ID Match API Original Draft] diff --git a/id-match-1.2.yml b/id-match-1.2.yml deleted file mode 100644 index ef49755..0000000 --- a/id-match-1.2.yml +++ /dev/null @@ -1,450 +0,0 @@ -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 5cbd359..ef49755 100644 --- a/id-match-api.yml +++ b/id-match-api.yml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - version: 1.1.0 + version: 1.2.2 title: ID Match API description: ID Match API Specification from Internet2 Trust and Identity, and Spherical Cow Group @@ -14,55 +14,11 @@ servers: paths: /people/{sorLabel}/{sorId}: - get: - tags: - - idMatch - summary: GET-based; Search only, similar to a regular request, except that a new identity will never be created as a result of the request - operationId: requestSerchOnlyGet - 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 - - in: query - name: name - schema: - type: string - description: The matching person's family name - - in: query - name: dateOfBirth - schema: - type: string - description: The matching person's date of birth - responses: - '200': - description: An existing identity was found matching the specified attributes. - content: - application/json: - schema: - type: string - example: - referenceId: M225127891 - '404': - description: Not found - content: - text/plain: - schema: - type: string - enum: ["No Match Found"] post: tags: - idMatch - summary: GET-based; Search only, similar to a regular request, except that a new identity will never be created as a result of the request + 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 @@ -99,6 +55,29 @@ paths: 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: @@ -113,9 +92,6 @@ paths: family: Lee dateOfBirth: "1983-03-18" identifiers: - - - type: referenceId - identifier: M225127891 - type: national identifier: 3B902AE12DF55196 @@ -124,16 +100,97 @@ paths: type: mobile number: 8185551234 referenceId: M523441767 - '400': - $ref: '#/components/responses/400Error' - '404': - description: Not found + '300': + description: Multiple Choices content: - text/plain: + application/json: schema: - type: string - enum: ["No Match Found"] + $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: @@ -176,8 +233,8 @@ paths: number: 8185551234 responses: - '200': - description: Return referenceId for a person known to ID Match. May return additional identifiers known to the Match service + '201': + description: Return new referenceId for a person new to ID Match content: application/json: schema: @@ -185,29 +242,22 @@ paths: example: names: - - type: official - given: Pat - family: Lee - dateOfBirth: "1983-03-18" - identifiers: - - - type: referenceId - identifier: M523441767 - - - type: enterprise - identifier: 905003148 - - - type: national - identifier: 3B902AE12DF55196 - - telephoneNumbers: - - - type: mobile - number: 8185551234 - + type: official + given: Pat + family: Lee + dateOfBirth: "1983-03-18" + identifiers: + - + type: national + identifier: 3B902AE12DF55196 + telephoneNumbers: + - + type: mobile + number: 8185551234 + referenceId: M523441767 - '201': - description: Return new referenceId for a person new to ID Match + '200': + description: Return referenceId for a person known to ID Match content: application/json: schema: @@ -218,11 +268,11 @@ paths: type: official given: Pat family: Lee - dateOfBirth: 1983-03-18 + dateOfBirth: "1983-03-18" identifiers: - - type: referenceId - identifier: M225127891 + type: national + identifier: 3B902AE12DF55196 telephoneNumbers: - type: mobile @@ -230,12 +280,6 @@ paths: referenceId: M523441767 - '300': - description: Multiple Choices - content: - application/json: - schema: - $ref: '#/components/schemas/people' '400': $ref: '#/components/responses/400Error' @@ -243,7 +287,8 @@ paths: get: summary: Server heartbeat operation description: >- - This operation should be available to all users. + This operation shows how to override the global security defined + above as we want to open it up for all users. security: [] responses: '200': @@ -343,6 +388,40 @@ components: 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 @@ -368,3 +447,4 @@ components: properties: message: type: string +