• Solution Overview
• Wellstorm Architecture
• Get More Info
• WITSML Over HTTP

Exchanging WITSML Documents Over HTTP

[UPDATE: This document has been superseded by the WIXP draft].

Introduction
WITSML SOAP API
REST approach
Service Discovery
Security Considerations
Conclusion

Introduction

This document outlines a procedure for exchanging WITSML documents over HTTP. The title refers to an architectural style named Representational State Transfer (REST), by Roy Fielding, lead author of the HTTP 1.1 specification. REST is the architectural style of the Web, and web services embodying REST participate in the network effects of being Web-friendly. Four interface constraints define the REST style:

1. Identification of resources Every resource on the web has a URI. If it doesn't have a URI, it's not on the web.
2. Manipulation of resources through representations. Web operations do not manipulate resources directly; they transfer resource representations (messages) between machines, and the machines modify resources accordingly.
3. Self-descriptive messages. The messages the machines exchange are marked up so that a machine or a human can interpret them.
4. Hypermedia as the engine of application state. Each web client holds the application's current state in the last message it received (for example, the current web page including its nested images). Hyperlinks in that message tell the web client how to execute transitions from the current state. The client holds all the state. Even complex, user-driven queries use hypertext: The server delivers forms that encode complex queries or updates into URLs or a POST entities; no client programs need understand a query language. The server always furnishes the client with a roadmap to the next state.

Many programmers find REST services more accessible than SOAP web services. The programming model is simple; GET and POST fulfill most operational needs. A web browser suffices for many applications. No generated glue code is necessary, so client programs may be written in languages lacking SOAP support.

WITSML SOAP API

The design of the WITSML SOAP API reflects the simplicity of the needs for data exchange among the collaborators in real time well operations management. The Store interface reproduces some of the functionality of the HTTP methods GET, POST, PUT, and DELETE. However the Store interface offers less functionality than those HTTP methods.

No URI: HTTP identifies resources by URI. Any web client software understanding URI can manipulate the resource. The Store interface identifies resources using its own scheme. After creating an object on a server, the only way to manipulate that resource is to use the Store interface. You cannot bookmark a wellLog.

No Caching: HTTP defines a caching protocol based on URI. Caches, including especially the client-side cache, can ask servers to transmit a resource if it is stale. The Store interface subverts HTTP caching. A WITSML server must retransmit a well log, which may not have been modified for months, in its entirety, each time it is requested.

Hard coded queries: Using hypertext forms languages (e.g. HTML forms, or XForms), servers can acquire articulate query parameters from forms-aware clients like web browsers, to perform complex queries and updates. A forms language permits the more capable servers to collect different parameters than less capable servers; no query language need be predefined. The Store interface employs a predefined query language supporting very limited queries; more capable servers have to be dumbed down.

All or nothing download: HTTP supports retrieval of byte ranges from documents. If a large download is interrupted using the Store interface, even when 90 percent complete, the client must restart the operation from the beginning. An HTTP request need only download the last 10 percent.

Synchronous only: HTTP permits a return code of 202 (Accepted) when a server wishes to indicate it will process a request asynchronously. The Store interface must operate synchronously – or rather the specification fails to declare concurrency constraints, so designers ought to assume that.

REST Approach

WITSML data objects like well, wellbore, and cementJob, are resources. Just having URI for these data objects, permits web applications to GET, PUT, and DELETE them. Any client can retrieve an object using GET, update it using PUT, and remove it using DELETE.

Now consider the Store interface methods AddToStore, GetFromStore, UpdateInStore, DeleteFromStore. We'll make each of these services available at different URI.

AddToStore: POST the WITSML data object to this URI. The server will create the object and return its URI in the Location header field of the HTTP response. Many client programs will need no other service. They will simply save this URI and manipulate the resource using GET, PUT, and DELETE.

GetFromStore: POST a WITSML query template to this URI. The server will return the usual WITSML query result in the response entity. Alternatively, the server may return HTTP code 303 See Other, along with the URI where the client can GET the result. The latter technique has the advantage that the GET is cacheable, while the POST is not; a client that makes the same query repeatedly on an object that is unchanging can reduce network traffic.

Note that GetFromStore returns query results, not the URI of any objects on the server; you cannot use the ordinary results of GetFromStore to obtain a listing of object URI. Servers should insert a URI in the <customData> element of each returned top level object:

	<customData><witsml-rest:uri
		ref="http://witsml.example.com/WELL.3297ab4cda0"
		xmlns:witsml-rest="http://www.witsml.org/rest" />
	<customData>

The witsml-rest namespace is some well-known namespace to be defined.

UpdateInStore: POST a WITSML update template to this URI. The server executes the update and returns. Note that while UpdateInStore offers extended functionality through its template mechanism, in many cases simply using HTTP PUT on a data object URI will suffice.

DeleteFromStore: POST a WITSML delete template to this URI. The server executes the delete and returns. Note that while DeleteFromStore offers extended functionality through its template mechanism, in many cases simply using HTTP DELETE on a data object URI will suffice.

Additionally, servers may offer extended capability for queries, updates, and deletes, richer than that available using the WITSML template language. A server can offer these services transparently to clients by exposing these services through a forms language like HTML forms, XForms, or other forms languages. The server can offer URI at which clients can GET these forms. The forms themselves contain the URI to which the form data should be submitted. The forms language defines conventions for serializing the form data. Thus, given a processor for a forms language, client programs need not “understand” the content of the forms; they simply present the rendered form to the user and the user submits the form, generating query results which clients do understand. This way, servers can obtain the parameters they need to exploit their unique capabilities. The most obvious example of using forms would be an HTML client program, but rich client applications, too, can embed forms processing plug-ins.

Defining MIME types and using them in the Content-Type HTTP headers can help web systems, most of which are unaware of WITSML, process messages correctly. We define MIME types for the HTTP entities in our messages. application/X-witsml+xml is the MIME type for WITSML data objects, either wrapped in their “pluralized” envelopes, or standing alone. application/X-witsml-template+xml is the MIME type for the WITSML template language.

The table below summarizes the capabilities a server may expose. A server may expose any, none, or all of them.

Service Discovery

Suppose http://witsml.example.com/ is the URL of a WITSML server. Our client software navigates to that URL, does a GET, retrieving a document of type application/X-witsml-service+xml. This document is the introspection document for the service, denoting URIs for the various subservices. In this way, client programs discover URIs of services each time they connect. This technique is robust against resources that may move over time. Even should the start URL for the WITSML server change, HTTP redirects can keep clients using the stale URL working.

	<?xml version="1.0" encoding"UTF-8"?>
	<witsmlService xml:base="http://witsml.example.com"/>
		<addToStore ref="/add"/>
		<getFromStore ref="/get"/>
		<updateInStore ref="/update"/>
		<deleteFromStore ref="/delete"/>
	</witsmlService>

This example server only exposes the basic WITSML functionality; it does not support forms based queries.

Security Considerations

WITSML applications using the procedures outlined here can be as secure as any web application, and as secure as WITSML SOAP services are today. Messages may be encrypted using SSL/TLS, and Basic authentication over SSL/TLS hides credentials from snoopers.

Conclusion

Servers can expose WITSML services using the principles that made the Web the most successful distributed application in history. Doing so increases the value of WITSML because users can leverage existing web technologies, like browsing, bookmarking, linking, and forms. Furnishing WITSML data objects with URI enables a host of new functionality. For example, semantic web descriptions of resources require URI; it will now be possible for a company to inventory metadata about the WITSML data objects it owns.

The procedure outlined here preserves all the capability of WITSML servers, while extending it, and making it simpler to write client programs. The semantics of the Store interface remain the same, so most servers could easily be fitted with this REST interface.