As of Q3 2015, the CIFER Project has been transitioned to the TIER-Data Structures and APIs Working Group. |
The Registry Extraction API is intended to make data available from an identity registry to downstream systems.
Currently, two models of obtaining data from the Registry are being considered. They are not mutually exclusive.
In pull operation, a client consuming notifications pulls changes from the Registry:
GET /v1/events?since=<serialnumber> 200 OK { "events": [ { "serialNumber":103, "sor":"registry", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123Z", "comment":"Updated name", "messageType":"diff", "attributes":{ "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ] } }, { "serialNumber":104, "sor":"registry", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:19.100Z", "comment":"Updated telephonenumber", "messageType":"diff", "attributes":{ "telephoneNumbers":[ { "type":"official", "number":"+1 646 555 1234", "verified":"no" } ] } } ] } |
An individual event can be retrieved by ID, or via a special request for the latest event.
GET /v1/events/<serialnumber> 200 OK { "serialNumber":103, "sor":"registry", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123Z", "comment":"Updated name" } |
GET /v1/events/latest 200 OK { "serialNumber":103, "sor":"registry", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123Z", "comment":"Updated name" } |
In push operation, the Registry sends changes to an endpoint (presumably a message queue or something similar):
PUT /v1/events/<serialnumber> { "serialNumber":103, "sor":"registry", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123", "comment":"Updated name" } |
The register operation can be used by other systems to trigger change notifications via the Registry.
POST /v1/events { "sor":"gms", "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123", "comment":"Updated membership" } 200 OK { "serialNumber":"108" } |
The Read API retrieves the set of attributes associated with a Registry Person. It is not quite the inverse of the write API, since the write API operates on an SOR Person Role.
The Person is identified using an identifier type (enterprise in this example) and the actual identifier.
GET /v1/people/enterprise/E87234345 200 OK { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "emailAddresses":[ { "address":"pat.lee@gmail.com", "type":"delivery" } ], "identifiers":[ { "identifier":"pl53", "type":"network" }, { "identifier":"E78967890", "type":"enterprise" } ], "sponsor":{ "identifier":"12345", "type":"enterprise" }, "roleEnds":"2014-08-04T12:00:00Z" } |
The Search API obtains a set of matching Registry People. Need to align with CIFER API Framework.
(HTML special characters not escaped here for readability.)
GET /v1/people GET /v1/people?sor=hrms GET /v1/people?name.given=j&name.family=smith GET /v1/people?sponsor=E87234345 GET /v1/people?validThrough=lt.2014-02-14 200 OK { "people":[ "/v1/people/enterprise/E57413693", "/v1/people/enterprise/E78967890", "/v1/people/enterprise/E87234345", ] } |
Use POST for more complicated searches?