UC Recruit Project Site

Updates, information, and documentation for UC Recruit, the system-wide academic employee recruitment web application

API: User Roles

This API is designed to facilitate automated user role management for customer campuses. It allows for creating, listing, finding and deleting a subset of the user roles in the system via a RESTful XML interface. This API does not allow modification of user roles created by the Admin “Manage Users” tool.  This is to prevent the API from overwriting manually added user roles (e.g.: administrator, diversity analyst, or other roles).

If you would like access to the API, please fill out the form here. This form helps us maintain control over who has access to the API and the information contained within.

Definitions

Schema

The API is designed to accept and return XML for requests.

Formally, UserRole is uniquely defined by its 4-tuple: (external-user-id, api-role-name, api-resource-type, api-resource-id).

  • The external-user-id for the customer campus corresponds to the Shibboleth eduPersonPrincipalName, e.g. 0123456789abcdef0123456789abcdef@ucsd.edu.
  • The api-role-name must be an analyst, Equity Advisor, professorial, or an approver role (see Specification: Access Control for the complete list).
  • The api-resource-type must be one of School, Department or Tool, and the api-resource-id must match the external_id of a School, Department, or the ‘recruit’ Tool.

Serialized IDs

The primary key for a UserRole is its serialized-id, a string representation of the unique 4-tuple that defines a UserRole.

Generating a Serialized ID

The serialized-id is formed by concatenating the external-user-id, api-role-name, api-resource-type, and api-resource-id together by ‘-‘s.

As an example, a UserRole 4-tuple of

(0123456789abcdef0123456789abcdef@ucsd.edu,Equity Advisor,School,1)

would have a serialized-id of

0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1

Quoting, XML, and URLs

The serialized-id may contain characters that need to be quoted or translated depending on the usage.

For XML, be sure to properly encode any XML entities, translating things like & to &

For URLs, be sure to properly URL encode the serialized-id, translating things spaces to %20. Additionally, encode any ‘.’s to ‘_’s.

Example Quoted Serialized IDs

Plain 0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1
XML 0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1
URL 0123456789abcdef0123456789abcdef@ucsd_edu-Equity%20Advisor-School-1

XML

Two XML formats are primarily used in the API: a Full Format and a Simple (Create) Format. We additionally give examples of a list of UserRoles, a 404 error, a create error, and a schema list.

Simple (Create) Format XML

You will need to use the Simple (Create) Format when you want to create a new UserRole.

<?xml version=”1.0” encoding=”UTF-8”?>
<user-role>
    <external-user-id>0123456789abcdef0123456789abcdef@ucsd.edu</external-user-id>
    <api-role-name>Equity Advisor</api-role-name>
    <api-resource-type>School</api-resource-type>
    <api-resource-id>1</api-resource-id>
</user-role>

Full Format XML

The Full Format is what is returned when retrieving a UserRole from the API. One should not mimic this format when attempting to create a new UserRole.

<?xml version=”1.0” encoding=”UTF-8”?>
<user-role id=”0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1”>
    <external-user-id>0123456789abcdef0123456789abcdef@ucsd.edu</external-user-id>
    <api-role-name>Equity Advisor</api-role-name>
    <api-resource-type>School</api-resource-type>
    <api-resource-id>1</api-resource-id>
    <internal-id readonly=”true” dangerous=”true”>5002</internal-id>
    <internal-role-id readonly=”true” dangerous=”true”>19</internal-role-id>
    <serialized-id readonly=”true”>0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1</serialized-id>
    <ingested-at readonly=”true”>2001-01-01T12:00:00-07:00</ingested-at>
    <auto readonly=”true”>true</auto>
</user-role>

Warning: Attributes labeled as dangerous are provided only for convenience purposes, and should never be relied on to be consistent between queries.

List Format

<?xml version=”1.0” encoding=”UTF-8”?>
<user-roles type=”array”>
  <user-role id=”0123456789abcdef0123456789abcdef@ucsd.edu-Recruit Analyst-School-1”>
    <external-user-id>0123456789abcdef0123456789abcdef@ucsd.edu</external-user-id>
    <api-role-name>Recruit Analyst</api-role-name>
    <api-resource-type>School</api-resource-type>
    <api-resource-id>1</api-resource-id>
    <internal-id readonly=”true” dangerous=”true”>4999</internal-id>
    <serialized-id readonly=”true”>0123456789abcdef0123456789abcdef@ucsd.edu-RecruitAnalyst-School-1</serialized-id>
    <ingested-at readonly=”true”>2001-01-01T12:00:00-07:00</ingested-at>
    <internal-role-id readonly=”true” dangerous=”true”>5</internal-role-id>
    <auto readonly=”true”>true</auto>
  </user-role>
  <user-role id=”0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1”>
    <external-user-id>0123456789abcdef0123456789abcdef@ucsd.edu</external-user-id>
    <api-role-name>Equity Advisor</api-role-name>
    <api-resource-type>School</api-resource-type>
    <api-resource-id>1</api-resource-id>
    <internal-id readonly=”true”  dangerous=”true”>5002</internal-id>
    <serialized-id readonly=”true”>0123456789abcdef0123456789abcdef@ucsd.edu-Equity Advisor-School-1</serialized-id>
    <ingested-at readonly=”true”>2001-01-01T12:00:00-07:00</ingested-at>    
    <internal-role-id readonly=”true”  dangerous=”true”>19</internal-role-id>
    <auto readonly=”true”>true</auto>
  </user-role>
</user-roles>

Error XML

The Error XML format is returned whenever there is an error creating a new UserRole.

<?xml version=”1.0” encoding=”UTF-8”?>
<errors>
  <error>Resource type (api-resource-type) must be in School, Department</error>
  <error>Role can’t be blank</error>
  <error>Role (api-role-name) must be in Recruit Analyst, Equity Advisor</error>
  <error>User can’t be blank</error>
</errors>

404 XML

The 404 XML format is returned whenever a resource cannot be found. An example is given below.

<?xml version=”1.0” encoding=”UTF-8”?>
<error>
  <message>Schema key must be one of ‘role-names’, ‘resource-types’, ‘required-xml-elements’</message>
</error>

406 Not Acceptable

Code 406 is returned when the server does not know what content-type to respond with. To resolve this, please try appending “.xml” to the end of the URL in order to explicitly request XML data:

https://apol-recruit.ucsd.edu/api/v1/user_roles.xml

Schema XML

Schema XML varies depending on the schema key being queried. An example is given below.

<?xml version=”1.0” encoding=”UTF-8”?>
<valid-role-names>
  <valid-role-name>Recruit Analyst</valid-role-name>
  <valid-role-name>Equity Advisor</valid-role-name>
</valid-role-names>

Working with the API

Requests listed below are prefixed with their necessary HTTP verb.

Making Valid Requests

It is strongly suggested that the following headers be set, or that all requests use a .xml suffix to ensure that XML responses are generated.

HTTP Header

Value

Content-Type

application/xml

Accept

application/xml

All POST requests should have XML bodies.

All API requests require HTTP Basic Authentication. Please see your systems administrator for assistance in defining the username and password for your site.

Listing All UserRoles

Lists the entire set of UserRoles:

GET https://apol-recruit.ucsd.edu/api/v1/user_roles[.xml]

Returns a List XML.

Listing UserRoles for a User

Lists the set of UserRoles defined for a particular user, given an external_user_id. For example, given 0123456789abcdef0123456789abcdef@ucsd.edu as an external_user_id:

GET https://apol-recruit.ucsd.edu/api/v1/user_roles/for/0123456789abcdef0123456789abcdef@ucsd_edu[.xml]
  • Returns a List XML with a 200 (OK) status code.
  • Returns 404 XML with a 404 (Not Found) status code if it is unable to find the user for the UserRole.

Finding a UserRole

Responds with the XML for a UserRole, when given its serialized-id:

GET https://apol-recruit.ucsd.edu/api/v1/user_roles/0123456789abcdef0123456789abcdef@ucsd_edu-Equity%20Advisor-School-1[.xml]
  • Returns Full Format XML with a 200 (OK) status code if found.
  • Returns 404 XML with a 404 (Not Found) status code otherwise.

Creating a UserRole

Creates a UserRole, given a request body containing Simple (Create) Format XML:

POST https://apol-recruit.ucsd.edu/api/v1/user_roles[.xml]
  • Returns Full Format XML with a 201 (Created) status code on successful create, with a Location header pointing to the newly created UserRole.
  • Returns Error XML with a 422 (Unprocessable Entity) status code if unable to create due to invalid XML data.
  • Returns 404 XML with a 404 (Not Found) status code if it is unable to find a matching user for the UserRole.

Deleting a UserRole

Deletes a UserRole, given its serialized_id:

DELETE https://apol-recruit.ucsd.edu/api/v1/user_roles/0123456789abcdef0123456789abcdef@ucsd_edu-Equity%20Advisor-School-1[.xml]
  • Returns an empty response with a 200 (OK) status code on success.
  • Returns 404 XML with a 404 (Not Found) status code if it is unable to find a matching API UserRole.

Schema Information

Lists the set of role names applicable to the API.

GET https://apol-recruit.ucsd.edu/api/v1/user_roles/schema/role-names[.xml]

Lists the set of resource types applicable to the API.

GET https://apol-recruit.ucsd.edu/api/v1/user_roles/schema/resource-types[.xml]

Lists the set of required XML elements to create a new UserRole.

GET https://apol-recruit.ucsd.edu/api/v1/user_roles/schema/required-xml-elements[.xml]
  • Returns Schema XML with a 200 (OK) status code if found.
  • Returns 404 XML with a 404 (Not Found) status code if it is unable to find schema information of the requested type.

Other Errors

If the API cannot properly process the request, you will receive a 500 (Internal Server Error) status code