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
URL:
http://163.153.114.103/api/requests/xStudents.json?navigationPage=1&navigationPageSize=1
Headers:
Accept: */* <style="padding-left: 30px;">Accept-Encoding: gzip <style="padding-left: 30px;">Authorization: bearer ZTk3MDcxZmItYmFiOS00ODYwLThiOTctNjM2OWZhYjk1Y2IxOlBhc3N3b3JkMQ
Parameters
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
Headers:
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
Body:
{
"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"
}
}