SOR-Registry Strawman Write API

Created by Benn Oshrin, last modified on Apr 16, 2014

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
`201 Created`	Request successfully processed
`400 Bad Request`	There was a problem with the data submitted
`401 Unauthorized`	Authentication required
`403 Forbidden`	Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return `401 Unauthorized` instead
`409 Conflict`	There is already a person or role with the specified identifer Since Add and Update use the same `PUT` request, this response cannot occur
`500 Other Error`	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
`200 Deleted`	Request successfully processed
`401 Unauthorized`	Authentication required
`403 Forbidden`	Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return `401 Unauthorized` instead
`404 Person Not Found`	The specified person is unknown
`404 Role Not Found`	The specified role is unknown
`500 Other Error`	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
`200 OK`	Request successfully processed
`400 Bad Request`	There was a problem with the data submitted
`401 Unauthorized`	Authentication required
`403 Forbidden`	Client is attempting to operate outside of its authority (eg: to the wrong SOR path)
`404 Person Not Found`	The specified person is unknown Since Add and Update use the same `PUT` request, this response cannot occur
`404 Role Not Found`	The specified role is unknown Since Add and Update use the same `PUT` request, this response cannot occur
`500 Other Error`	Unknown error

No labels

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
- Permalink
- Apr 03, 2013
1. 128507@ucsf.edu
  OpenIDM's API reference may be of interest, as well:
  
  http://openidm.forgerock.org/doc/integrators-guide/index/appendix-rest.html
  Permalink
  
  Apr 03, 2013
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.
- Permalink
- Apr 03, 2013
1. 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
  
  http://tools.ietf.org/wg/scim/
  
  http://datatracker.ietf.org/wg/scim/
  Permalink
  
  Apr 03, 2013
  1. 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).
    
    Permalink
    
    Apr 03, 2013
    1. 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.
      
      Permalink
      
      Apr 03, 2013
2. Benn Oshrin
  Just a simple copy and paste error. Fixed now, thanks.
  Permalink
  
  Apr 07, 2013
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:
- Permalink
- Mar 02, 2016

Child pages

About the Write API

Methods

SOR Person Role Added

Request Using Separate Person-Level and Role-Level Attributes

Response

Request Using Person-Level Attributes Expressed As Role-Level Attributes

Requesting Assignment of SORID

SOR Person Role Deleted

Response

SOR Person Role Updated

Request Using Separate Person-Level and Role-Level Attributes

Request Using Person-Level Attributes Expressed As Role-Level Attributes

Response

8 Comments