API Source

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.

Modes

Installation

This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.

Configuration

ApiSource supports three modes of operations:

• Push Mode: The System of Record sends records to ApiSource via ApiSource's API
• Pull Mode: ApiSource queries the System of Record via the SoR's API (not yet implemented)
• Poll Mode: ApiSource polls an endpoint (typically a message bus) for records to process (not yet implemented)

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

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.

Pull Mode

Not yet implemented.

Poll Mode

Not yet implemented.

Endpoints and Actions

Push Mode

The URL prefix for ApiSource operating in Push Mode is

https://server.org/registry/api_source/coid/v1/sorPeople/sorlabel/sorid

where

• coid: The CO ID for this instance of ApiSource
• sorlabel: SOR Label, as configured for the ApiSource instance
• sorid: The System of Record's unique ID for the record being presented

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.

Pull Mode

Not yet implemented.

Poll Mode

Not yet implemented.

Message Format

PUT (Request) / GET (Response)

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:

• addresses*
• affiliation
• dateOfBirth
• department
• emailAddresses*
• identifiers*
• names*
• organization
• telephoneNumbers*
• title
• urls*
• validFrom / validThrough

*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",
        "organization": "School of Philosophy and Biopharmacology",
        "department": "Department of Metaphysics",
        "title": "Associate Professor of Metaphysical Microbiology",
        "dateOfBirth": "1990-04-25",
        "validFrom": "2019-09-01T00:00:00Z",
        "validThrough": "2020-08-31T23:59:59Z",
        "identifiers": [
            {
                "type": "national",
                "identifier": "541-00-3732"
            }
        ],
        "emailAddresses": [
            {
                "type": "personal",
                "address": "patxlee@email.nil",
				"verified": true
            }
        ],
        "addresses": [
            {
                "type": "home",
                "streetAddress": "3593 Red Maple Drive",
                "locality": "Los Angeles",
                "region": "CA",
                "postalCode": "90046",
                "country": "US"
            }
        ],
        "telephoneNumbers": [
            {
                "type": "home",
                "number": "323-555-1208"
            }
        ],
        "urls": [
            {
                "type": "personal",
                "url": "https://metaphysics.spb.ac.nil/plee"
            }
        ]
    }
}

PUT (Response)

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"
        }
    ]
}

See Also

• cm_api_sources
• cm_api_source_records