HTTP headers
OSLC provides various values in the header section of HTTP requests and responses to exchange additional information in transactions. These header values support features such as stable paging, conditional updates of resources, or to ensure that duplicate transactions do not occur following a HTTP connection failure.
Conditional updates based on Etag values and If-Match headers
An entity tag (ETag) is a value that is included in a HTTP header response that represents the current state of a resource. When an OSLC consumer application makes a GET request, the response header includes an ETag value. The consumer application includes the ETag value as part of an If-Match header in subsequent PUT and PATCH update requests to ensure that changes are conditional and are made only if the record has not changed since the ETag value was created. The conditional update process detects bad updates and race conditions, for example when two consumers try to update the same resource.
The consumer application stores the ETag header value and sends it as part of HTTP If-Match header for a subsequent update request. The server evaluates the If-Match header and determines whether the consumer application has an old version or the most recent version of the resource. If the server determines that the consumer application has the most recent version of the resource, the update is implemented unless any business validation or database constraints are found. If the server determines that the request contains an old version of the resource, it returns an HTTP 412 precondition failed response. The consumer application must get the resource again and submit an update request that is based on the updated ETag.
The consumer application can submit an update request without an If-Match header or with the If-Match header value set to * (asterisk). Submitting this request is semantically equivalent to having no If-Match header in the update request. In both cases, the update is unconditional. If the resource that is referred by the URI exists and no business validation or database constraints are found, the update is implemented.
Stable paging for collection resources
OSLC stable paging defines a paging pattern where the resource that is paged does not change when it is being paged to the consumer application, for example to a mobile device. Stable paging is supported only for collection resources and is not the default paging format of HTTP servers. To request stable paging, the OSLC consumer application includes the stablepaging query parameter in the HTTP request or includes a stablepaging header in the request. The server loads the requested collection resource in memory and the HTTP response redirects the OSLC consumer application to the URI where the loaded collection resource is stored. Subsequent requests for the next pages always load from the in-memory resource and never from the database. Stable paging results in better performance as the consumer application pages through the results.
Stable paging requires that the subsequent request for the next page is served by the same server process or cluster member that served the initial request for stable paging. The same server process is required because the resource is loaded in the memory of that server process, not in the other cluster members. If a subsequent request is load balanced to other members, the consumer application receives a 404 Not Found error. To avoid this error, ensure that in-session requests from a consumer application are all served by the same server process.
Example of stable paging
The client requests an asset resource:GET/oslc/os/oslcasset?stablepaging=true303 Redirecting
Location: http://host:port/../olscasset?stableid=1234GET../oslcasset?stableid=1234The response is the first page of the collection. The URI for the next page is embedded in the oslc:ResponseInfo object as part of the message. As the client moves through the pages, the pages expire after they load. If the client is at page 3, page 3 cannot be reloaded, nor can page 1 or page 2. Any attempt to reload those pages generates an HTTP 410 error. The loaded resource stays in memory until it expires based on an idle expiry time that is controlled by using the mxe.oslc.idleexpiry system property. The idle expiry time indicates the period that the resource was not accessed by the client. The client can request member properties by using the oslc.select clause and order the resulting collection by using the oslc.orderBy query parameter.
Setting the PATCHTYPE header to merge for partial resource updates
To minimize message size, for example for mobile applications, consumer applications can use PATCH requests to limit updates to changed data only. To update the child objects of an object structure, for example to update the work log that is associated with a work order, the consumer application sends a PATCH request, where the PATCHTYPE header property is set to merge.
Returning resource properties in HTTP response headers
Maximo IT implementation of OSLC includes a new HTTP header property, called properties, that supports the return of resource attribute values in HTTP responses. A consumer application can set the propeties header and include a comma-separated string of properties in a POST, PUT, or PATCH request. The HTTP response includes th requested attribute values in the HTTP response. The properties header can be used, for example, to receive the number of a work order in the HTTP response to the POST request that created the work order.
Avoiding duplicate transactions following connection failures
Maximo IT implementation of OSLC includes a new HTTP header property, called transactionid, that a consumer application can use to assign a unique ID to each transaction. The provider application stores the transaction IDs in the OSLC transaction table. Following a network connection failure, if the consumer application resends a POST or PATCH request, the server validates the transaction ID against the values in the transaction table. If the transaction ID already exists, the server returns a transaction conflict error in the HTTP response.