Registry v4.0.0 introduces the Core API, a collection of higher level APIs that provide transaction-oriented operations, rather than the lower level, model-oriented REST API v1. The Core API is implemented as a standard Plugin that is enabled by default.
Enabling Core APIs
Core APIs must be enabled, and each instantiation is associated with an (unprivileged) API User. Before continuing, create any desired API User(s). To instantiate an API, go to Configuration > Core APIs > Add a New Core API. Select the desired API and API User.
Core CO Person APIs are accessed using an Identifier on the CO Person record, not the internal CO Person ID that shows up (for example) in the CoPerson API. This implies an Identifier of the specified type is available on all relevant CO Person records, see Extended Types and Configuring Registry Identifier Assignment for possibly helpful resources. Select the desired Identifier Type in the Core API configuration.
It is possible to create multiple instantiations, for example to
- Grant access to a Core API to multiple API Users
- Grant access to multiple Core APIs to the same API User
- Expose the same records using multiple Identifier Types
When a request is processed, if there is more than one valid configuration for the authenticated API User, it is non-deterministic as to which configuration will be used.
Granting an API User access to the Write API will also grant access to the Read API. Do not create two entries for the same API User for each API, as Write access may be denied depending on which configuration is returned first by the database.
Authentication
Core APIs use Basic Auth, using the API Username and API Key as created for the API User.
CO Person Read API
The CO Person Read API creates a consolidated view of most attributes associated with a CO Person, including
- CoGroupMember
- CoPersonRole
- Address
- AdHocAttribute
- TelephoneNumber
- EmailAddress
- Identifier
- Name
- OrgIdentity
- Address
- EmailAddress
- Identifier
- Name
- TelephoneNumber
- Url
- Url
- Authenticators
- Clusters
The Core APIs do not support Extended Attributes, which are deprecated. AdHoc Attributes should be used instead. Alternately, the REST API v1 can be used to manage Extended Attributes.
Read API Endpoint
| Request Method | GET |
|---|---|
| URL |
where
|
Message Format
The response is a JSON document as described by this JSON Schema.
CO Person Write API
The CO Person Write API is a collection of three APIs allow creation, updating, and deletion of CO Person records.
The Create and Delete APIs are not currently implemented. (CO-2152)
The Create and Update APIs accept the same attributes as returned by the Read API. Note that most metadata returned by the Read API is not permitted (and will be ignored) in the Write API. The exception is the sub-element id, which when present is used to indicated the update of an existing sub-element (such as an EmailAddress) rather than the creation of a new one.
The Write API cannot be used to update attributes that are not normally modifiable via other mechanisms, including
- Automatic Group Memberships
- Attributes attached to Org Identities created from Organizational Identity Sources
Update API Endpoint
| Request Method | PUT |
|---|---|
| URL |
where
|
Message Format
For the Create and Update APIs, the request is sent with Content-Type of application/json with a body containing a JSON document as described by this JSON Schema. An empty body or document is not valid for Create or Update. There is no request body for the Delete API.