Child pages
  • SOR-Registry Strawman Write API
Skip to end of metadata
Go to start of metadata

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. (warning) 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

  1. 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.

    1. 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

      1. 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).

        1. Sorry, careless reading on my part.  Will see how the CIFER/SCIM alignment discussions go.  I expect this will get addressed.

    2. Just a simple copy and paste error. Fixed now, thanks.

  2. 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: