From 18e5e8f0fc60a4dcd7b787daf4619e4c3637bc5c Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 10 Feb 2021 12:33:24 -0600 Subject: [PATCH 1/4] Create id-match-api.json --- id-match-api.json | 746 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 746 insertions(+) create mode 100644 id-match-api.json diff --git a/id-match-api.json b/id-match-api.json new file mode 100644 index 0000000..d8faef6 --- /dev/null +++ b/id-match-api.json @@ -0,0 +1,746 @@ +{ + "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/api/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": { + "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" + } + } + } + }, + "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" + } + } + } + }, + "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 + } + } + } + }, + "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": 4115 + }, + { + "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" + } + ] + } + ] + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/400Error" + } + } + }, + "put": { + "tags": [ + "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", + "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/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": 4115 + }, + { + "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": { + "200": { + "description": "Return referenceId for the person indicated in the reconciliation request", + "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" + } + } + } + }, + "201": { + "description": "Return referenceId for the new person specified in the reconciliation request", + "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" + }, + "409": { + "$ref": "#/components/responses/409Error" + } + } + } + }, + "/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" + } + } + } + } + } + }, + "409Error": { + "description": "A forced reconciliation request is being attempted using out of date information", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } +} From 93e19d553e2bcce8a69f95f455c5794a4a06cd97 Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 10 Feb 2021 12:34:27 -0600 Subject: [PATCH 2/4] Update README.adoc --- README.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/README.adoc b/README.adoc index 59085ec..864e7a5 100644 --- a/README.adoc +++ b/README.adoc @@ -19,5 +19,6 @@ 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.2.2] + +link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.yml[JSON 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] From 039bfc4d0b546d8dcd0f4d5949aa6f4633133e3c Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 10 Feb 2021 12:35:37 -0600 Subject: [PATCH 3/4] Update README.adoc --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 864e7a5..44c9701 100644 --- a/README.adoc +++ b/README.adoc @@ -19,6 +19,6 @@ 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.2.2] + -link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.yml[JSON mapping of ID Match API Specification 1.2.2] + +link:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.json[JSON 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] From b33e03e068876460794e91a1e5645246142538ef Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Wed, 10 Feb 2021 12:37:50 -0600 Subject: [PATCH 4/4] Update README.adoc --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 44c9701..b699dbf 100644 --- a/README.adoc +++ b/README.adoc @@ -20,5 +20,5 @@ Editor: {Editor}, {Email} 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:https://github.internet2.edu/api-schema/idMatchApi/blob/master/id-match-api.json[JSON 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] +link:https://spaces.at.internet2.edu/display/cifer/SOR-Registry+Strawman+ID+Match+API[ID Match API Original Draft] + +link:id-match-spec.adoc[ID Match API Original Draft in asciidoc] +