API Objectives and Constraints

4 API Objectives and Constraints

The API is specified in function-call syntax, and specifies simple data types (integers, strings, etc) for parameters and return values. Pointers and structures are not used.

Unless noted otherwise, function calls are synchronous (blocking).

The concurrent use of API functions by multiple client applications is dependent on the particular API implementation.

This specification describes only the external interfaces exposed by the API, not any particular implementation. The internal implementation of the API can and will vary. All references in this document to implementation scenarios are for the purpose of example only.

5 Use Cases

5.1Sensor Data over WITSML

The sensor aggregator system is the Publisher and the office system is the Subscriber. The realtime data objects are “pushed” from the Publisher to the Subscriber.

The first phase in the process involves “subscribing” to one or more of the Publisher’s available realtime data channels. To do this, the potential Subscriber sends a subscription request to the Publisher. The subscription request will specify, among other things, that the Subscriber wishes to receive the WITSML realtime data object and which channels of the realtime object.

In order to know what data object types and realtime channels it can request, the Subscriber can first ask the Publisher for that information.

The Subscriber can determine what data object types are available by using SOAP to invoke the Publisher’s WMLP_GetCap (Get Capabilities) function, denoted by (1) in the diagram below.

The Publisher's WMLP_GetCap function returns the Publisher’s Capabilities object (2) to the Subscriber, which lists the data object types the Publisher can provide. In this example, the Publisher would list only the realtime data object type in the returned Capabilities object, as that is the only data object type it can publish.

The Subscriber then needs to know what channels are available for the realtime object. This information is not conveyed in the Publisher's Capabilities object, since it can vary by well, wellbore or time. Instead, the Subscriber can query the Publisher for this information (3), using the WMLS_GetFromStore function. For example, the following query would return the channel mnemonics and well/wellbore identifiers for all realtime objects on the Publisher (4).

If the Subscriber already knew the well/wellbore identifiers, it could have specified them in the query:

This could result in a smaller result set and a quicker, more efficient query.

Once the Subscriber has determined which channels on which wells and wellbores are available to be published, it then invokes the Publisher’s WMLP_Subscribe function (5) and subscribes to one or more realtime channels. Included in the Subscription request (which is itself passed as a WITSML data object) are the Subscriber’s host name and various other information that the Publisher will need when it has data to send to the Subscriber. The Subscriber also passes its own Capabilities object to the Publisher. ¹ Thus, both the Publisher and Subscriber now know each other’s capabilities.

So that subscriptions are not lost across restarts of the Publisher system, the Publisher then records the subscription in a non-volatile store (7) and returns a unique subscription identifier to the Subscriber (6). The Subscriber can later use this subscription identifier to cancel, modify or verify the subscription.

Once the subscription has been accepted, we are then ready for the second phase of the process: publishing the data.

Whenever new or changed data for the specified channels become available – perhaps immediately after the subscription was received or at some time later - the sensor aggregator application will create a WITSML realtime data object and send it to all Subscribers who are subscribed to that channel of the realtime data object.

The sensor aggregator application is responsible for parsing the data coming in from the sensors, associating that data to the appropriate data items defined for the WITSML realtime data object, supplying any missing data items and creating the WITSML realtime data objects.

The sensor aggregator application then uses HTTP/S POST to send the WITSML data objects to the Subscriber, as denoted by (2) in the diagram on the next page.

On the Subscriber system, a process running under a Web server receives the WITSML data objects (3), ² extracts the data items from the data object and then persists them to its own internal data store (4).