About the Write API
This API is used to send SOR information to the Identity Registry.
Methods
SOR Person Role Added
It is up to the Identity Registry to determine how to map the provided attributes to its internal data model.
In these examples, hrms is the SOR, X12345 is the SORID, and R98765 and R98766 are SOR Role IDs. The SOR Role ID must be unique for the SOR Person, but need not be unique across all SOR Roles.
Request Using Separate Person-Level and Role-Level Attributes
PUT /v1/sorPeople/hrms/X12345 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18" } } PUT /v1/sorPeople/hrms/X12345/R98765 { "sorAttributes": { "title":"Professor of Phrenology" "percentTime":"50%" } } PUT /v1/sorPeople/hrms/X12345/R98766 { "sorAttributes": { "title":"Administrative Assistant" "percentTime":"20%" } }
Response
Response |
Description |
---|---|
|
Request successfully processed |
|
There was a problem with the data submitted |
|
Authentication required |
|
Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return |
|
There is already a person or role with the specified identifer Since Add and Update use the same |
|
Unknown error |
The Identity Registry may return a Reference Identifier if identity match is not called separately. (The other ID Match responses may apply, as well.)
201 Created { "referenceId":"M225127891" }
Additional attributes, such as identifiers, may also be returned, or may be returned instead.
201 Created { "referenceId":"M225127891", "identifiers":[ { "identifier":"pl53", "type":"network" } ], "emailAddresses":[ { "address":"pat.lee@university.edu", "type":"official" } ] }
Request Using Person-Level Attributes Expressed As Role-Level Attributes
In this example, the SOR is capable of representing Person-Level Attributes, but the Identity Registry is not. This example also applies where the Identity Registry is capable of representing Person-Level Attributes, but the SOR is not.
PUT /v1/sorPeople/hrms/X12345/R98765 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18" "title":"Professor of Phrenology" "percentTime":"50%" } } PUT /v1/sorPeople/hrms/X12345/R98766 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18" "title":"Administrative Assistant" "percentTime":"20%" } }
Requesting Assignment of SORID
To support cases where a Registry is maintaining authoritative records on behalf of an SOR, but the user interface is not provided by the Registry, it is possible to request addition of a record without providing an SORID. It is then up to the Registry to assign a new SORID and return it in the response.
POST /v1/sorPeople/guest { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "emailAddresses":[ { "address":"pat.lee@gmail.com", "type":"personal" } ] } }
201 Created { "referenceId":"M225127891", "identifiers":[ { "identifier":"GUEST000797031", "type":"sor" }, { "identifier":"pl53", "type":"network" } ] }
Registries that require the use of role record identifiers will also need to assign and return a role record identifier.
201 Created { "referenceId":"M225127891", "identifiers":[ { "identifier":"1853737", "type":"role" }, { "identifier":"GUEST000797031", "type":"sor" }, { "identifier":"pl53", "type":"network" } ] }
To add an additional role to an existing SORID, use the following example. GUEST000797031
is the SOR ID. Note the use of POST
to distinguish from an SOR Person Role Add Request Using Separate Person-Level and Role-Level Attributes.
POST /v1/sorPeople/guest/GUEST000797031 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "emailAddresses":[ { "address":"pat.lee@gmail.com", "type":"personal" } ] } }
201 Created { "referenceId":"M225127891", "identifiers":[ { "identifier":"1853738", "type":"role" }, { "identifier":"GUEST000797031", "type":"sor" }, { "identifier":"pl53", "type":"network" } ] }
SOR Person Role Deleted
DELETE /sorPeople/hrms/X12345/R98765
Response
Response |
Description |
---|---|
|
Request successfully processed |
|
Authentication required |
|
Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return |
|
The specified person is unknown |
|
The specified role is unknown |
|
Unknown error |
SOR Person Role Updated
Request Using Separate Person-Level and Role-Level Attributes
PUT /v1/sorPeople/hrms/X12345 { "sorAttributes": { "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18" } } PUT /v1/sorPeople/hrms/X12345/R98765 { "sorAttributes": { "title":"Professor of Cosmology" "percentTime":"50%" } }
Request Using Person-Level Attributes Expressed As Role-Level Attributes
PUT /v1/sorPeople/hrms/X12345/R98765 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18", "title":"Professor of Cosmology" "percentTime":"50%" } }
Response
Response |
Description |
---|---|
|
Request successfully processed |
|
There was a problem with the data submitted |
|
Authentication required |
|
Client is attempting to operate outside of its authority (eg: to the wrong SOR path) |
|
The specified person is unknown Since Add and Update use the same |
|
The specified role is unknown Since Add and Update use the same |
|
Unknown error |
8 Comments
Keith Hazelton (wisc.edu)
These RESTful methods called to my mind the SCIM stuff:
http://tools.ietf.org/html/draft-ietf-scim-api-00
See also Chris Phillips introductory article: http://www.internetsociety.org/articles/introduction-simple-cloud-identity-management
128507@ucsf.edu
OpenIDM's API reference may be of interest, as well:
http://openidm.forgerock.org/doc/integrators-guide/index/appendix-rest.html
128507@ucsf.edu
I am curious why a successful response to DELETE is 201 and not 200 or 204. According to the HTTP 1.1 spec (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.7) DELETE should return 200, 202, or 204. According to the SCIM draft, DELETE returns a 200.
Keith Hazelton (wisc.edu)
There is an IETF WG on SCIM now, to get on the mailing list and ask these kinds of questions, go to https://www.ietf.org/mailman/listinfo/scim
See also
128507@ucsf.edu
My question centered more around why the CIFER DELETE API uses 201 for success, and not why SCIM is using 200 (which seems reasonable to me).
Keith Hazelton (wisc.edu)
Sorry, careless reading on my part. Will see how the CIFER/SCIM alignment discussions go. I expect this will get addressed.
Benn Oshrin
Just a simple copy and paste error. Fixed now, thanks.
Hyzer
Based on TIER common elements, this: PUT /v1/sorPeople/hrms/X12345 should be PUT /v1/sorPeople/hrms:X12345
Based on TIER common elements, this: PUT /v1/sorPeople/hrms:X12345/R98765 should be PUT /v1/sorPeople/hrms:X12345/Roles/R98765
There are not well defined set of roles? I think PUT /v1/sorPeople/hrms:X12345/Roles/R98765 assigned a role to a user, but shouldnt create a role that doesnt exist... so a 404 role doesnt exist could occur
Response in the table above should have response code and success like this page: TIER API Basic Group Management Operations#Responsecodes: