Witsml/> Core Application Program Interface Version 1



Download 0.54 Mb.
Page1/21
Date31.07.2017
Size0.54 Mb.
#24987
  1   2   3   4   5   6   7   8   9   ...   21
<WITSML/>
Core
Application Program Interface
Version 1.3.1


9 December 2005

This document was produced by POSC in conjunction with the

WITSML Technical Review Team members.



www.posc.org
Copyright (c) 2005 Petrotechnical Open Standards Consortium, Inc. (POSC). All rights reserved.

POSC® and the POSC logo® are registered trademarks and WITSML™ and the WITSML logo™ are trademarks of POSC.


This file is distributed under the POSC License Agreement at http://www.posc.org/about/license.shtml.
Use of this file constitutes agreement with the POSC License Agreement.

Table of Contents



1 Introduction 6

2 Document Revisions 7

3 Terminology and Basic Concepts 9

3.1 [WITSML] Object or Data Object 9

3.2 Unique Identifiers (UIDs) 10

3.3 Representation versus Transport 11

3.4 Transport versus Storage 12

3.5 [WITSML] Document 12

3.6 Subscribe/Publish Application Program Interface (API) 12

3.7 Client/Server Application Program Interface (API) 13

3.8 Versioning 13

3.8.1 Versioning - Data Objects 13

3.8.2 Versioning - API Signature 14

3.8.3 Versioning - API Capabilities 14

3.8.4 Versioning - Executable Programs 15

3.8.5 Incrementing Version Numbers 15

4 API Objectives and Constraints 16

5 Use Cases 17

5.1 Sensor Data over WITSML 17

5.2 Rig Site Repository/Aggregator 21

6 The Interfaces 23

6.1 STORE and PUBLISH 23

6.2 Choosing an Interface 24

6.3 Common Behavior 25

6.3.1 Case Sensitivity 25

6.3.2 Query and Subscription Templates 26

7 STORE Interface 28

7.1 Introduction 28

7.2 Query Templates 30

7.2.1 Introduction 30

7.2.2 Data Item Selection 32

7.2.3 Object Selection 33

7.2.4 Combining Data Item and Object Selection 34

7.2.5 Selection using Recurring Data Items 36

7.2.6 Minimum Query Template 39

7.3 Authentication and Encryption 41

7.4 Capabilities Objects 42

7.4.1 Client Capabilities (capClient) Object 42

7.4.2 Server Capabilities (capServer) Object 42

7.4.3 Capabilities by Object 43

7.5 STORE Functions 46

7.5.1 WMLS_AddToStore 47

7.5.2 WMLS_DeleteFromStore 49

7.5.3 WMLS_GetBaseMsg 52

7.5.4 WMLS_GetCap 53

7.5.5 WMLS_GetFromStore 54

7.5.6 WMLS_GetVersion 57

7.5.7 WMLS_UpdateInStore 58

7.6 STORE Interface - WSDL File 61

7.6.1 File Listing 62

7.6.2 Narrative 69

8 PUBLISH Interface 71

8.1 Introduction 71

8.2 Subscription Requests 74

8.2.1 action attribute - the action being requested 76

8.2.1.1 action=”add” - add a new subscription 76

8.2.1.2 action=”modify” - modify an existing subscription 76

8.2.1.3 action=”cancel” - cancel one or all existing subscriptions 77

8.2.1.4 action=”verify” - verify an existing Subscription 78

8.2.1.5 action=”retransmit” - retransmit the realtime headers 80

8.2.2 retCode attribute - the return code 81

8.2.3 idSub attribute - the subscription identifier 81

8.2.4 test attribute - test network connectivity 82

8.2.5 host, process, port and encrypt attributes - specify the subscriber’s URL 83

8.2.6 idPub attribute - identify the Publisher 84

8.2.7 retry attribute - the error retry count 85

8.2.8 updateInterval attribute - limit the publication rate 86

8.2.9 Subscription Object Attribute Summary 87

8.3 Subscription Templates 88

8.3.1 Realtime Example 91

8.4 Publishing and Maintaining Subscriptions 95

8.5 POST Request 96

8.5.1 Syntax 96

8.5.2 Notes: 97

8.5.3 Example: 97

8.6 Authentication and Encryption 98

8.7 Capabilities Objects 99

8.7.1 Subscriber Capabilities (capSubscriber) Object 99

8.7.2 Publisher Capabilities (capPublisher) Object 99

8.7.3 Capabilities by Object 100

8.8 PUBLISH Functions 103

8.8.1 WMLP_GetBaseMsg 103

8.8.2 WMLP_GetCap 104

8.8.3 WMLP_GetVersion 105

8.8.4 WMLP_Subscribe 106

8.9 PUBLISH Interface - WSDL File 108

8.9.1 File Listing 109

8.9.2 Narrative 113

9 APPENDIX A - Example Data Object Schema 115

10 APPENDIX B - Unit of Measure 121

10.1 Overview 121

10.2 Basics 121

10.3 Process interaction with ‘uom’ 122

10.4 Responsibilities 123

10.5 Updating 123

11 APPENDIX C - Defined Values 124

11.1 Return Values 124

12 APPENDIX D – Special Handling 126

12.1 Randomly growing objects 128

12.2 Systematically Growing Objects 129

12.3 STORE and PUBLISH behavior 131

12.4 STORE Interface Examples 136

12.4.1 trajectory Data Object Example 138

12.4.2 mudLog Data Object Example 141

12.4.3 log Data Object Example 144

12.4.3.1 Querying for Rows in a Systematically Growing Object 148

12.4.3.2 Updating Rows in a Systematically Growing Object 155

12.4.3.3 Deleting Rows in a Systematically Growing Object 157

12.4.3.4 Adding Columns in a Systematically Growing Object 159

12.4.3.5 Deleting Columns in a Systematically Growing Object 160

12.5 PUBLISH Interface Example 161

13 APPENDIX E - Service Agreement 163

14 APPENDIX F - Custom Data 165

14.1 Namespace 165


1 Introduction


This document describes the core components of the WITSML Version 1.3.1 API. The core components consist of the Client/Server and Subscribe/Publish interfaces.

2 Document Revisions


Since Revision 0 (the v1.3.0 specification)

Changed all version references from “1.3.0” to “1.3.1”. Changed all namespace designations from “130” to “131”. This excludes the WSDL namespaces which changed from "130" back to "120". Changed the data schema namespace in all XML examples from "130" to "131ex" to reflect the example schema in Appendix A.

Deleted attribute "apiVers" from element "function" in examples (the attribute was deleted in 1.3.0).

Consistently italicized all WMLS_ references.

Deleted all references to the Supplemental API specification.

The following changes are for the indicated issues:

Issue 1.3-14 "WSDL namespace not backward compatible"


  1. Clarified that data schema version values must match the version attribute in the plural container object.

  2. Changed WMLS_GetVersion to return a comma delimited list of data schema versions (without spaces) instead of returning the software version.

  3. Documented the "dataVersion" OptionsIn parameter in WMLS_GetCap and WMLP_GetCap so the client can tell the server the data schema version for which capability information is desired.

  4. Changed the ReturnAllElements OptionsIn parameter in WMLS_GetFromStore and WMLP_Subscribe to have a keyword and value format with the keyword being "returnElements" and the values being "all" or "requested" (default).

  5. Documented that the OptionsIn parameter string is encoded utilizing the encoding rules for HTML form content type application/x-www-form-urlencoded as specified at http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.3.3.

Issue 1.2-139 " Retrieving the server-specific UID-prefix info"
Modified WMLS_AddToStore to document that if a uid is not specified for the object, then the server will assign a uid value to the object and return the value in 'SuppMsgOut' (if there is no error). Child uids must be populated by the client.

Issue 1.3-24 " Suggested clarification for query templates"


Clarify that Object Selectors will be returned in addition to Data Item Selectors.

Issue 1.3-27 " Side effects of updates to growing objects"


Documented in section 12.3 STORE and PUBLISH behavior that in growing objects, any request to update a server query element will be ignored without issuing an error.



Download 0.54 Mb.

Share with your friends:
  1   2   3   4   5   6   7   8   9   ...   21




The database is protected by copyright ©ininet.org 2024
send message

    Main page