Component 2: Infrastructure

To get started, the infrastructure required is very simple – it uses a REST interface. xPress Roster is even simpler, in that it only utilizes READ operations.

If you are not familiar with REST, check out this tutorial ‘What is REST?’.

Your returned data comes back, not as files, but as XPress Roster objects. Usually data is stored in relational databases on both ends of the wire; however it is up to the implementer to choose their own approach to storing and/or viewing data. However a good XPress Roster product serializes or parses the passed objects one page at a time.

More API details can be found in the examples below and in the SIF Infrastructure Implementation Specification 3.1.


Security & Other Supporting Standards

Just like OAuth 2.0, SIF 3 relies heavily on existing Internet grade security. This includes the use of TLS (HTTPS) to prevent the reading of intercepted messages. Other standards are also leverage to create a robust ecosystem. While this document further profiles the SIF 3 Product Standard understanding the information and requirements within it, is required when certifying a SIF 3 xPress Roster solution.

SIF 3 Adaptors fulfill different roles. For the first release of xPress Roster the Service Provider holds the data and returns it when requested. While one or more Service Consumer makes requests of the Service provider. These roles may expand as more and more SIF 3 features are utilized.


Retrieving Data

In this section do not worry about the data returned. In fact, you do not even have to consider why we get back the data that we do. Instead direct your thoughts to how to build and/or service requests.

Below are samples of requests and responses, including additional field definitions. For a complete list of all field definitions, refer to the SIF Infrastructure Implementation Specification 3.1.

The Root URL

Example GET



Accept: */*
<style="padding-left: 30px;">Accept-Encoding: gzip
<style="padding-left: 30px;">Authorization: bearer ZTk3MDcxZmItYmFiOS00ODYwLThiOTctNjM2OWZhYjk1Y2IxOlBhc3N3b3JkMQ



The Request, Response, and Event columns use the standard SIF Characteristics. Tables used throughout this and other documents include one of the following primary (and mutually exclusive) element characteristics:

M – Mandatory. The element must appear in every Create Event and, where not specifically excluded in a conditional Request, in every Response message issued by the Service Provide as well. If a Create Request does not specify one or more Mandatory elements, the request is erroneous.

Q – ReQuired. If the element appears in the original Create Event or is eventually included in an Update Event (i.e. once it is known to the Service Provider), it must be returned in all corresponding queries as if it were Mandatory.

D – RecommenDed. The element is optional, but we encourage systems to provide these fields to establish baseline communications.

O – Optional. The element may or may not appear in any message relating to the object. The Provider need not support it.


One or more of the following qualifiers may also appear with the above characteristics:

C – Conditional. The element is treated as the accompanying primary characteristic only if the specified conditions are satisfied. Otherwise the element is omitted from the message. Specifically:

MC – If conditions are such that the element can legally be included, it must be

OC – If conditions are such that the element can legally be included, it may be.

I – Immutable. The value of the element cannot be changed once it is supplied.

U – Unique. The value of this element for each object of this type must be unique (ex: ID)

N – Non-Queryable. The element value is often calculated (ex: an aggregate), and cannot be used as a search key in a conditional Query Request.

R – Repeatable. The element may appear more than once.


The Conveyed column using the following abbreviations:

H – HTTP Header

Q – URL Query Parameter

M – URL Matrix Parameter

P – URL Path

When more than one conveyance is utilized or a conditional is indicated, see the explanation for details of it use.


Likely Request Parameters

HTTP Header Field Name Request Response Event Conveyed Explanation
Accept O HP Used to indicate when JSON is expected in the response (application/json). If omitted, may also be indicated by including the “.json” extension in the URL’s path. Otherwise results will be conveyed using the default, XML.
access_token MC Q The token used to authenticate the sender of the message, authorizing the requested action. Usually the token/hash value of the Authorization header. This query parameter is only required when the Authorization header is not set or another authentication standard is leveraged.
navigationPage O MC HQ The number of the Page to be returned. If it is outside the range of results (which does not constitute an error) an HTTP Response with a code of 204 (No Content) will be returned.
navigationPageSize MC MC HQ This is included in every Paged Query Request, and indicates the number of Objects to be returned in the corresponding Response Page. If the Page Size specified is too large for the Service or Environments Provider to supply, an Error with code 413 (Response too large) will be returned. When contained in the Response, it indicates the actual number of objects on the returned Page.
timestamp MC M M HQ Date / Time of Event creation (in ISO-8601 format also used as the basis of xs:dateTime) If not need for authentication, may be omitted in the request. If needed, only for requests this value may be provided as a URL query parameter instead of a header.


Example Response

Status Line:

HTTP/1.1 200 OK


Content-Type: application/json
<style="padding-left: 30px;">navigationCount: 1
<style="padding-left: 30px;">providerId: NERIC01
<style="padding-left: 30px;">navigationLastPage: 1
<style="padding-left: 30px;">timestamp: 2015-10-27T18:51:33Z
<style="padding-left: 30px;">Server: Apache-Coyote/1.1
<style="padding-left: 30px;">messageType: RESPONSE
<style="padding-left: 30px;">Date: Tue, 27 Oct 2015 22:51:33 GMT
<style="padding-left: 30px;">responseAction: QUERY
<style="padding-left: 30px;">Content-Length: 1993
<style="padding-left: 30px;">navigationPage: 1
<style="padding-left: 30px;">navigationPageSize: 1
<style="padding-left: 30px;">environmentURI: http://localhost:8080/api/environments/44524a80-b71b-49cc-8bf2-250000b6712b
<style="padding-left: 30px;">relativeServicePath: /xStudents.json


  "xStudents": {
    "xStudent": {
      "@refId": "D47B7B88-CE17-44FB-B94F-0000E5BA0532",
      "name": {
        "type": "LegalName",
        "familyName": "Pitts",
        "givenName": "Jennifer",
        "middleName": "X"
      "localId": "471777",
      "stateProvinceId": "735668753",
      "address": {
        "addressType": "Mailing",
        "line1": "936 Cedar Drive",
        "city": "MOUNT VERNON",
        "stateProvince": "NY",
        "countryCode": "US",
        "postalCode": "10552"
      "phoneNumber": {
        "phoneNumberType": "Cell",
        "number": "5552585105",
        "primaryIndicator": "false"
      "email": {
        "emailType": "Organizational",
        "emailAddress": "JenniferPitts@JohnsonCityMS.edu"


Likely Response Parameters

HTTP Header Field Name Request Response Event Conveyed Explanation
Content-Type MC M M HP Tells the receiver how to parse the body of the message. Supported: application/JSON, application/xml (default). Must be conveyed whenever a body is present. May be omitted in a request. In that case the mime type is either: The mime type indicated on the URL (i.e. .JSON) XML if not defined on the URL or the HTTP Header See also: Accept
environmentURI OC H May be returned by the environment provider where the environment is pre-provisioned.
messageType O M M H One of: EVENT/REQUEST/RESPONSE/ERROR If not provided, it will default to REQUEST.
navigationCount O H The total number of objects in the set of results generated by the initial Paged Query that is associated with the returned navigationId.
navigationLastPage O H It is included as an aid for the Consumer in detecting when to stop issuing Paged Query Requests.
relativeServicePath MC H Replicates all information contained in the segments of the Request URL following the Request Connector. This could include the Service name, XQuery Template name or Service Path defining the payload format, and any accompanying URL matrix parameters (Context and Zone). No URL Query parameters are included. The Environments Provider places it into all delayed Responses (and would therefore not be supplied by a Service Provider in a Brokered Architecture), as an aid to stateless Consumers. It is optional for immediate Responses.
requestId MC MC H Only required for delayed Requests. A Consumer specified “token” that uniquely identifies every delayed Request issued by the Consumer. It could be as simple as a monotonically increasing integer. Used to correlate the delayed (asynchronous) Response with the original Request. It could be as simple as a monotonically increasing integer.
responseAction M H This must exactly match the requestAction value contained in the HTTP header of the Request being responded to. Valid values are: CREATE/UPDATE/DELETE/QUERY
timestamp MC M M HQ Date / Time of Event creation (in ISO-8601 format also used as the basis of xs:dateTime) If not need for authentication, may be omitted in the request. If needed, only for requests this value may be provided as a URL query parameter instead of a header.


Identifying Success

Any of a number of 2XX and 3XX status codes may be returned in HTTP Responses to indicate that the action requested by the Consumer (or in the case of publishing an Event, the Provider) contained in the HTTP Request was received, understood, accepted and processed “successfully”.

HTTP Code Meaning Example of Use
200 OK The standard HTTP response code for all successful HTTP requests, with the exceptions noted below
201 Objects Created One or more objects have been successfully created
202 Accepted The SIF Request contained in the HTTP request has been accepted for routing, but the processing has not been completed. This is the status code returned in the HTTP response to every delayed SIF Consumer Request, as well as every published SIF Provider Event.
204 No Content All change Requests have Responses with contents. This is the response to a Query for which no existing object qualified.
304 Not modified The specific response when a Query asks for objects which have changed, and none have


Possible Errors

There is also a range of standard HTTP Error Codes (4XX and 5XX) that will be returned in case of Error. Whenever a SIF Error object is returned in response to a Request a known HTTP Error Code will be returned in the HTTP Status field. This field can have one of the following values:

HTTP Code Meaning Example of Use
400 Bad Request XML error, version problems or error specific to a particular object type such as the omission of a mandatory element or an unsupported query or an unsupported order clause
401 Unauthorized Illegal Consumer Authorization token accompanying the request
403 Forbidden Consumer Authorization token is legal, but Consumer is not authorized to issue the requested operation
404 Not Found Object ID does not correspond to an existing object. This can occur for Query as well as Update or Delete operations
405 Method not Allowed Paged Query Request issued to Object URL rather than Object List URL.
409 State Conflict An attempt has been made to create an existing object.
412 Precondition Failed An attempt has been made to modify an object when the Requester was not basing the modification on the latest version.
413 Response too large A non-paged Query returning all objects was too large for the Service Provider (or Broker) to include in a single Response message.
500 Internal Service Error An unexpected error occurred in servicing the Request.
503 Service Unavailable Returned only for Consumer Requests requiring an immediate Response. This error indicates that the expected Service processing time for the Request is great enough that the Consumer must reissue it as a Request requiring a delayed Response.


Example Error

HTTP/1.1 401 Unauthorized
<style="padding-left: 30px;">responseAction: QUERY
<style="padding-left: 30px;">messageType: ERROR
<style="padding-left: 30px;">Server: Apache-Coyote/1.1
<style="padding-left: 30px;">Content-Type: application/json
<style="padding-left: 30px;">Content-Length: 156
<style="padding-left: 30px;">Date: Fri, 23 Oct 2015 19:40:09 GMT
<style="padding-left: 30px;">timestamp: 2015-10-23T15:40:09Z
<style="padding-left: 30px;">relativeServicePath: /xStudents.json
<style="padding-left: 30px;">providerId: NERIC01
  "error": {
    "@id": "e1e19242-0654-4f5f-bea7-50b4e6cb29b0",
    "code": "401",
    "message": "Not Authorized.",
    "description": "No or invalid Authorization Token provided"


<–Component 1: Authentication
Component 3: Data–>