This plugin is experimental, and interfaces may change across minor releases. |
The API Organizational Identity Source Plugin is designed to integrate using RESTful APIs and message buses.
The API implemented is based on, but not identical to, the CIFER SOR-Registry Strawman Write API.
|
This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.
ApiSource supports three modes of operations:
All three modes may be used concurrently, so long as a single SORID space is in effect. (ie: All three modes will share the same unique key for the same record subject.)
ApiSource must be instantiated once per System of Record.
Push Mode requires the creation of an API User. The specified API User will have read/write access to the ApiSource API, the endpoint of which is made available via the ApiSource configuration page. It is recommended to create an Unprivileged CO API User for this purpose, though any defined API User may be used.
Push Mode does not support Org Identity Sync via Job Shell or at Login. Technically, no errors will be thrown, but because Push Mode does not support calling out to the System of Record, no updates will be made.
Not yet implemented.
Not yet implemented.
The URL prefix for ApiSource operating in Push Mode is
https://server.org/registry/api_source/coid/v1/sorPeople/sorlabel/sorid
where
coid and sorlabel are used to find the correct instantiation of ApiSource.
The following actions are supported in Push Mode:
DELETE
: Remove the specified record from the set of records associated with this SoR. No body is expected.GET
: Obtain the current record for the specified SOR ID. The response will be a record in the same format as was PUT
.PUT
: Add a record for the specified SOR ID, or update an existing record. The body of the request is in the message format described below.The following HTTP Response Codes may be returned:
200
: An existing record was found and deleted, returned, or updated (as appropriate for the action).201
: The record was successfully stored and processed (PUT
only).401
: Unauthenticated / authorization failed.404
: The specified record does not exist (DELETE
or GET
only).500
: An error occurred.Not yet implemented.
Not yet implemented.
The message format is a JSON object with a single member, sorAttributes
. sorAttributes
, in turn, is an object whose members are from the following list of available attributes, as defined in the SOR-Registry Core Schema Specification:
*Plural attributes may have multiple values, provided via a JSON array
The message should be sent with a Content-Type
header of text/json
.
{ "sorAttributes": { "names": [ { "type": "official", "given": "Pat", "middle": "X", "family": "Lee" } ], "affiliation": "faculty", "dateOfBirth": "1990-04-25", "identifiers": [ { "type": "national", "identifier": "541-00-3732" } ], "emailAddresses": [ { "type": "personal", "address": "patxlee@email.nil", "verified": true } ] } } |
The message format is a JSON object, currently with a single member: identifiers
, representing a list of identifiers associated with the CO Person created by or attached to the SOR record. Additional attributes may be returned in the future.
{ "identifiers": [ { "identifier": "1049f0d5-04cc-4ad5-8ab4-b6e056227dcb", "type": "reference" }, { "identifier": "pxl28", "type": "network" } ] } |