diff --git a/README.adoc b/README.adoc index c65a4c4..ddcd0d3 100644 --- a/README.adoc +++ b/README.adoc @@ -2,8 +2,8 @@ = Internet2, InCommon Trusted Access Platform and Spherical Cow Group :Email: hazelton@internet2.edu -:Date: 2020-11-04 -:Revision: 04 +:Date: 2021-02-10 +:Revision: 06 :SelfLink: https://github.internet2.edu/api-schema/idMatchApi :Editor: Keith Hazelton :Email: hazelton@internet2.edu @@ -15,8 +15,9 @@ Self-link: {SelfLink} + Editor: {Editor}, {Email} ==== + ==== Partial Specification for ID Match API -link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.yml[YAML mapping of ID Match API Specification 1.1] + -link:id-match-spec.adoc[ID Match API Specification 1.1] + +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: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 new file mode 100644 index 0000000..ef49755 --- /dev/null +++ b/id-match-1.2.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 +