| H. Winkler | |
| Wellstorm Development | |
| March 2006 |
Well Information Exchange Protocol: WIXP
draft-winkler-wixp-00
This memo presents a protocol that uses HTTP to exchange, update, and delete Wellsite Information Transfer Standard Markup Language (WITSML) documents.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
The WITSML SIG has defined a body of XML document types ([WITSML131])for describing entities in oil and gas drilling. Additionally, it has defined SOAP protocols for exchanging and modifying that data. That protocol has been successful in meeting its goal of enabling the flow of well site data between operators and service companies. Yet implementation of that protocol can be complex, limiting the adoption rate among vendors with less direct need for the full search and update semantics in that protocol.
To encourage broader implementation, and to enhance accessibility by many different kinds of clients, this specification defines a protocol for document exchange based on HTTP and the architecture of the web ([W3C.WD-webarch-20040816]).
This specification does not modify any WITSML document formats. It specifies only a protocol for exchanging and modifying them. To implement this specification, clients and servers just obey the rules of HTTP [RFC2616], and understand a simple document type, that locates the WITSML documents on the server.
A WIXP service exposes two kinds of resources: The WITSML documents themselves, and XML documents describing how to find them. The service identifies each resource by a URI [RFC3986]. Client applications use HTTP methods GET, POST, PUT and DELETE to retrieve and manipulate these resources:
Most of the rules governing client-server interaction are simple HTTP. WIXP-aware clients and servers understand, additionally, the meanings of the repository description documents, and that POSTing to the URIs of growing WITSML objects will append to them.
When given the URI of a repository, clients GET a document from that URI.
Client Server
| |
| 1.) GET Repository URI |
|----------------------------------------->|
| |
| 2.) Repository CDD |
|<-----------------------------------------|
| |
The Repository Description Document (RDD) is described in Section 7. Below is a short example of the root RDD for a repository:
<repository xmlns="http://www.witsml.net/ns/repository">
<name>Our WITSML Repository</name>
<object type="bhaRun">
<link rel="collection" href="bhaRun">bhaRuns</link>
</object>
<object type="cementJob">
<link rel="collection" href="cementJob">cementJobs</link>
</object>
<object type="well">
<link rel="collection" href="well">wells</link>
</object>
<object type="wellbore">
<link rel="collection" href="wellbore">wellbores</link>
</object>
</repository>
Figure 1
Servers MUST expose a RDD at some URI. The RDD SHOULD enumerate collection links for well objects, so that clients can traverse a hierarchy of contained objects to locate the objects of interest. The RDD MAY enumerate collection links for all object types, as a shortcut.
Having obtained the RDD, the client can locate collections of WITSML documents by following the <link> elements whose rel attribute is "collection".
Clients obtain more RDDs by following collection links in the repository's root RDD as described in Section 4.1. A collection link is a <link> element whose rel attribute is "collection".
Client Server
| |
| 1.) GET Collection URI |
|----------------------------------------->|
| |
| 2.) Repository Description Document |
|<-----------------------------------------|
| |
Below is a sample RDD that might have been obtained by following the collection link from the wellbore object in the example in Figure 1:
<collection xmlns="http://www.witsml.net/ns/repository" >
<object type="wellbore">
<name>TEST WELLBORE 1</name>
<date>2006-03-10T11:32:27.038-06:00</date>
<link rel="instance" href="TEST-WB-1">XML</link>
<link rel="contains" href="TEST-WB-1-C">Contains</link>
<link rel="view" href="TEST-WB-1-V">View</link>
</object>
<object type="wellbore">
<name>TEST WELLBORE 2</name>
<date>2006-02-06T15:06:22.624-06:00</date>
<link rel="instance" href="TEST-WB-2">XML</link>
<link rel="contains" href="TEST-WB-2-C">Contains</link>
<link rel="view" href="TEST-WB-2-V">View</link>
</object>
<object type="wellbore">
<name>TEST WELLBORE 3</name>
<date>2006-02-06T15:04:35.426-06:00</date>
<link rel="instance" href="TEST-WB-3">XML</link>
<link rel="contains" href="TEST-WB-3-C">Contains</link>
<link rel="view" href="TEST-WB-3-V">View</link>
</object>
</collection>
The RDD enumerates the objects in the collection. It describes metadata about the object, and may contain several links for each object. Each wellbore object in the sample above contains links to the XML object itself, to a collection of "contained objects" per the WITSML containership hierarchy, and to a view resource. None of these link types are mandatory. A server may choose not to support a view link type, or it may choose links to expose or hide based on the user's privileges.
If the user has appropriate privileges, servers SHOULD supply a link to contained objects for well, wellbore, and any other WITSML objects that can contain other other objects. Servers SHOULD supply a link to the instance data . Servers SHOULD supply metadata including the object's name and date.
Clients can add documents to a repository by POSTing documents to the repository URI:
Client Server
| |
| 1.) POST Repository URI |
|----------------------------------------->|
| |
| 2.) 201 Created |
|<-----------------------------------------|
| |
If the server successfully added the document to the repository, it SHOULD return HTTP 201 Created, and return the URI it has assigned to the new object in the Location header. This is just the behavior specified by [RFC2616].
To get, update or delete a WITSML document in the repository, applications use the GET, PUT and DELETE methods respectively, on the URI of the document itself. This is just the behavior specified by [RFC2616]. Additionally, we will define what it means to POST to a WITSML document URI. We described how to obtain these URIs in Section 4.2.
In Content-type headers, WITSML documents SHOULD have the type "application/witsml+xml" once registration for that type has completed per [RFC4288]
Servers MUST support GET on WITSML document URIs.
Client Server
| |
| 1.) GET Document URI |
|----------------------------------------->|
| |
| 2.) WITSML Document |
|<-----------------------------------------|
| |
To retrieve a document, clients execute GET on its URI. To assure that clients and caches can detect stale objects, servers SHOULD follow the "Rules for When to Use Entity Tags and Last-Modified Dates" in Section 13.3.4 of [RFC2616]. When retrieving documents for later modification with PUT, clients should record the returned entity tag or modification date.
Servers MAY support PUT on WITSML document URIs.
To update a document a client will previously have obtained the document from its URI using GET. The client then modifies the document and executes PUT on its URI.
Client Server
| |
| 1.) GET Document URI |
|----------------------------------------->|
| |
| 2.) 200 OK |
|<-----------------------------------------|
| |
| 3.) PUT Modified Doc to URI |
|----------------------------------------->|
| |
| 4.) 200 OK |
|<-----------------------------------------|
| |
Clients SHOULD request the PUT conditionally, using HTTP headers If-Unmodified-Since or If-Match. Doing so prevents overwriting changes made to the document since the last time the client retrieved it.
Servers MAY support DELETE on WITSML document URIs.
Client Server
| |
| 1.) DELETE Document URI |
|----------------------------------------->|
| |
| 2.) 200 OK |
|<-----------------------------------------|
| |
To delete a document from the repository, clients execute DELETE on its URI.
Servers MAY support POST on WITSML document URIs. This section prescribes the meaning of POST on a WITSML document URI.
Client Server
| |
| 1.) POST Document URI + fragment |
|----------------------------------------->|
| |
| 2.) 204 No Content |
|<-----------------------------------------|
| |
Several WITSML object types are called "growing objects" For example, log objects accumulate <data> elements. A client may POST a WITSML fragment in the entity of a request to the document's URI. If supporting this behavior, the server SHALL append the fragment to the appropriate growing portion of the document. This is consistent with [RFC2616]'s description of POST : "The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource". If POST is successful, the server SHOULD return 204 No Content, as no new resource has been created.
For the log example, the client would POST one or more <data> elements:
POST HTTP/1.1
Host: witsml.example.org
Content-Type: text/plain; charset="UTF-8"
Content-length: 106
<data>846.00000,-999.00000,-999.00000,17.50000</data>
<data>846.50000,-999.00000,-999.00000,9.10000</data>
The Content-type for posting a fragment MUST NOT be "application/witsml+xml"
A server may support POSTing other media types to a document URI, or POSTing to non-growing WITSML objects. This specification does not define any expected behavior for doing so.
An RDD may have either a <repository> element <collection> as its root element.
A document with a root <repository> element describes the repository as a whole.; a document with a root <collection> element describes collections within a repository.
A document with a root <collection> element describes collections within a repository.
The <name> element supplies a human readable name for the collection
The <object> embodies a collection of information about an object or an object type.
The type attribute specifies the WITSML object type
The <name> element supplies a human readable name for the object
<link> describes a hyperlink to some resource associated with the object.
The href is the URI of a resource.
The rel attribute tells the meaning or relation of the link. Any string is allowed. Certain strings are currently defined, and all clients SHOULD understand these:
RDDs are extensible. Clients MUST ignore elements and attributes they don't recognize. This schema will evolve by adding elements and attributes to the default namespace in Section 8. Servers may also extend the document format by adding names and attributes from private namespaces, anywhere in the document.
[provisional]
default namespace = "http://www.witsml.net/ns/repository"
any = anyAttribute | text | anyElement
anyAttribute = attribute * { text }
anyElement = element * { (anyAttribute | text | anyElement)* }
object = element object {
attribute type { xsd:NCName },
(date? &
link*)
}
date = element date {
attribute type { xsd:NCName },
link*
}
repository = element repository {
anyAttribute* ,
(
element name { text },
(anyElement* | object*)*
)
}
collection = element collection {
anyAttribute* ,
(
element name { text }?,
(anyElement* | object*)*
)
}
link = element link {
((attribute href { text },
attribute rel { xsd:NCName }) |
anyAttribute*),
text
}
start = (repository | collection)
Servers typically need to restrict access to resources according to the user's identity. This specification does not limit the mechanism that servers may employ. For greatest interoperability servers and clients should support the Basic and Digest mechanisms described in [RFC2617]. These mechanisms are vulnerable to replay attacks unless the session is encrypted using TLS ([RFC2246]).
Most owners of well information consider it sensitive. All data should be exchanged over a secure channel according to [RFC2246].
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. |
| [RFC2246] | Dierks, T. and C. Allen, “The TLS Protocol Version 1.0”, RFC 2246, January 1999. |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999. |
| [RFC2617] | Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, S.D., Leach, P.J., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication”, RFC 2617, June 1999. |
| [RFC3986] | Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, January 2005. |
| [RFC4288] | Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures”, BCP 13, RFC 4288, December 2005. |
| [WITSML131] | “WITSML v1.3.1 API Specification”, 2005. |
| [ATOMPUB] | Gregorio, J and B de hOra, “The Atom Publishing Protocol”, 2006. |
| [W3C.WD-webarch-20040816] | Walsh, N and I Jacobs, “Architecture of the World Wide Web, First Edition”, W3C LastCall WD-webarch-20040816, August 2004. |
| [WITSML-ORG] | POSC, “WITSML SIG”, 2006. |