Registry Extraction API

The Registry Extraction API is intended to make data available from an identity registry to downstream systems.

Use Cases

Provisioning LDAP
Connecting to a provisioning system (directly or via a message queue/ESB/etc)
Tight binding of applications to the Registry (including an Identity Console)

Models

Currently, two models of obtaining data from the Registry are being considered. They are not mutually exclusive.

Read API: A fairly rich, RESTful API to obtain data from the Registry on demand.
Notification API: When data is changed in the Registry, a notification is made available (specific mechanics TBD). Initially, this design will be simple, conveying only that a change happened for a person, and possibly providing all of that person's data. The recipient of the message will need to determine what, if anything, is of interest. This API can operate via push or pull, although a given Registry need not support both.

Notification Strawman

Pull

In pull operation, a client consuming notifications pulls changes from the Registry:

GET /v1/events?since=<serialnumber>

200 OK
{
  "events":
  [
    {
      "serialNumber":103,
      "entity":"/v1/people/49873",
      "timestamp":"2012-10-04T03:10:14.123Z"
    },
    {
      "serialNumber":104,
      "entity":"/v1/people/49873",
      "timestamp":"2012-10-04T03:10:19.100Z"
    }
  ]
}

serialNumber allows a client to pull new changes by indicating the last change it saw. As such, the value must be comparable, with later events having later serial numbers.
entity is a reference to a resource obtainable via the Read API.
TBD: Can a client send a filter to restrict the events it wishes to see?

Push

In push operation, the Registry sends changes to an endpoint (presumably a message queue or something similar):

PUT /v1/events/<service>/<serialnumber>
{
  "serialNumber":103,
  "entity":"/v1/people/49873",
  "timestamp":"2012-10-04T03:10:14.123"
}

service is an identifier to indicate the source (eg: Registry, GMS, etc) of the event.

Read API

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

Search API

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=<2014-02-14

Open Questions

Can we come up with a better name?
Should attributes be conveyed with the change event?
How should entity be more formally defined?

Child pages