DAP4: Capabilities and Versioning

From OPeNDAP Documentation
Revision as of 04:25, 18 April 2012 by EthanDavis (talk | contribs)

<-- back to OPULS Development

--EthanDavis 13:32, 16 April 2012 (PDT)

1 Background

Providing OPeNDAP clients with information on the particular capabilities of a given server and given dataset has been discussed many times. Types of capabilities include supported DAP versions, supported server-side functions. Another possible capability would be support for multiple encodings of the various OPeNDAP services. Providing capabilities documents can also make it easier to plan for extensibility and the future evolution of OPeNDAP.

Negotiating versions using HTTP headers or URL keywords is described in DAP 4.0 Design doc. Advertising DAP protocol services is described in the DAP Service Terminus document.

2 Problem addressed

The proposal attempts to address the following requirements:

  • Support for multiple versions of DAP protocol in a backwards compatible way
  • Support for extensibility and evolution of protocol
  • Support for multiple encoding formats (media types) for each resource type
  • Support description of server and dataset capabilities (e.g., server-side processing capabilities)

3 Proposed solution

Provide dataset capabilities documents from the raw DAP dataset URL. A dataset's capabilities document includes links to the various OPeNDAP services for that dataset. Each link is described with a link relationship type and a media type. The link relationship type indicates what type of resource will be returned. The media type indicates the document type in which the returned resource will be encoded.

Providing a dataset capabilities document with links to both DAP2 and DAP4 resources allows for DAP2 backward compatibility and will support protocol extensibility and future evolution of the protocol.

3.1 Raw DAP Dataset URLs Return Capabilities Documents

A GET request on a DAP dataset URL (e.g., http://server.org/some/path/data.nc) returns the capabilities document for the dataset. To take advantage of web caching, capabilities documents should try to be light weight (i.e., quick creation) and as stable as possible.

A dataset capabilities document must contain a server section and a dataset section.

The server section should include

  • a link to the full server capabilities document (if applicable)
  • a list of the DAP versions the server supports
  • the implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")
  • a list of extensions the server supports

The dataset section should include

  • a link to the full dataset capabilities document (this document)
  • links to all available OPeNDAP services for the dataset
  • a list of extensions the dataset supports
  • a list of the types of constraint expressions supported for this dataset
  • a list of the types of processing instructions supported for this dataset

Dataset capabilities documents can be encoded in the following media types:

  • application/vnd.opendap.org.capabilities+xml
  • application/vnd.opendap.org.capabilities+json
  • application/vnd.opendap.org.capabilities+pbuf

Definitions of these media types can be found in :

  • The DAP4 Capabilities XML schema (link) which is declared in the namespace http://opendap.org/ns/dap/capabilities.
  • The DAP4 Capabilities JSON definition (link).
  • The DAP4 Capabilities protobuf definition (link).

A link to a Dataset Capabilities document can be identified by the following link relationship type:

  • http://opendap.org/rel/dap/dataset

The URL of a link with this relation type can be used to GET the dataset capabilities document for the dataset.

An example of an HTTP request for an XML encoded dataset capabilities document is given below.

3.2 DAP4 DDX

A DAP4 DDX document describes the structure of a dataset and contains other metadata for that dataset.

DAP4 DDX documents can be encoded in the following media types:

  • application/vnd.opendap.org.dap4.ddx
  • application/vnd.opendap.org.dap4.ddx+pbuf

Definitions of these media types can be found in:

  • The DAP4 DDX XML schema (link) which is declared in the namespace http://opendap.org/ns/dap4/ddx.
  • The DAP4 DDX JSON definition (link).
  • The DAP4 DDX protobuf definition (link).

A link to a DAP4 DDX document can be identified by the following link relationship type:

  • http://opendap.org/rel/dap4/ddx

The URL of a link with this relation can be used to GET a DAP4 DDX resource.

3.3 Extension Resource Types

A number of extensions to the core DAP4 protocol have been discussed. Here are a few extensions and some resource types that we might consider:

  • DAP4 Asynchronous Request/Response
    • Asynchronous information (http://opendap.org/rel/dap/asynchronous)
  • DAP4 Server-Side Processing
    • Processing instructions (http://opendap.org/rel/dap4/processing)

4 Rationale for the solution

  • Allows servers full control of their URL space
      • DAP4 URLs are identified by their link type rather than a hard wired "file extension".
      • On the other hand, file extensions can also be supported.


5 Discussion


5.1 DAP4 Data

5.1.1 Link Relationship Type

http://opendap.org/rel/dap4/data

The URL of a link with this relation can be used to GET or POST a DAP4 data resource. (POST is used if a dataset session is desired, i.e., to freeze dynamically changing datasets, or if an asynchronous response is expected.)

5.1.2 Possible Media Types

  • application/vnd.opendap.org.dap4.data
  • application/vnd.opendap.org.dap4.data+ascii
  • application/vnd.opendap.org.dap4.data+json
  • application/vnd.opendap.org.dap4.data+ncstream

A representation encoded in one of these media types contains DAP4 data.

5.2 DAP4 Constraint Expression

5.2.1 Link Relationship Type

5.2.2 Possible Media Types

  • application/vnd.opendap.org.dap4.ce
  • application/vnd.opendap.org.dap4.ce+xml

A representation encoded in one of these media types contains a DAP4 constraint expression.

5.3 DAP4 Processing Instructions

5.3.1 Link Relationship Type

5.3.2 Possible Media Types

  • application/vnd.opendap.org.dap4.processing+ferret
  • application/vnd.opendap.org.dap4.processing+grads
  • application/vnd.opendap.org.dap4.processing+jython
  • application/vnd.opendap.org.dap4.processing+jvm

A representation encoded in one of these media types contains processing instructions for the DAP4 server.

5.4 DAP4 Server Capabilities Documents

5.4.1 Link Relationship Type

5.4.2 Possible Media Types

6 DAP2 Resource Types

6.1 DAP2 DAS

6.1.1 Link Relationship Type

6.1.2 Possible Media Types

application/vnd.opendap.org.dap2.das

A representation of this media type contains a DAP2 DAS document.

6.2 DAP2 DDS

6.2.1 Link Relationship Type

6.2.2 Possible Media Types

application/vnd.opendap.org.dap2.dds

A representation of this media type contains a DAP2 DDS document.

6.3 DAP2 DDX

6.3.1 Link Relationship Type

6.3.2 Possible Media Types

application/vnd.opendap.org.dap2.ddx

A representation of this media type contains a DAP2 DDX document declared in the namespace http://opendap.org/nc/dap2/ddx.

6.4 DAP2 Data

6.4.1 Link Relationship Type

6.4.2 Possible Media Types

  • application/vnd.opendap.org.dap2.data
  • application/vnd.opendap.org.dap2.data+ascii

A representation of one of these media types contains DAP2 data. See the DAP2 specification for details.

6.5 DAP2 Constraint Expression

6.5.1 Link Relationship Type

6.5.2 Possible Media Types

  • application/vnd.opendap.org.dap2.ce

A representation of this media type contains a DAP2 constraint expression. Generally used as a DAP2 data URL query string. See the DAP2 specification for details.

7 Examples

7.1 Example Server Capabilities Response/Request

Client uses DAP dataset URL, http://server.org/dap/path/data.nc, to GET the dataset capabilities resource as an XML document:

GET /dap/path/data.nc HTTP/1.1
Host: server.org
Accept: application/vnd.opendap.org.capabilities+xml

The response might look like like:

200 OK
Content-Type: application/vnd.opendap.org.capabilities+xml;charset=UTF-8

<capabilities xmlns="http://opendap.org/ns/dap/capabilities">
  <server rel="http://opendap.org/rel/dap/server"
          type="application/vnd.opendap.org.capabilities+xml,
                application/vnd.opendap.org.capabilities+json,
                application/vnd.opendap.org.capabilities+pbuf"
          href="http://server/dap/capabilities">
    <protocolVersions>
      http://opendap.org/rel/dap2
      http://opendap.org/rel/dap3
      http://opendap.org/rel/dap4
    </protocolVersions>
    <implVersion>TDS 4.3.54</implVersion>
    <supportedExt>...</supportedExt>
  </server>
  <dataset rel="self"
           type="application/vnd.opendap.org.capabilities+xml,
                 application/vnd.opendap.org.capabilities+json,
                 application/vnd.opendap.org.capabilities+pbuf"
           href="http://server/dap/path/data.nc">
    <version name="dap2">

      <serviceLink rel="http://opendap.org/rel/dap2/das"
                   type="application/vnd.opendap.org.dap2.das"
                   href="http://server/some/path/data.nc.das"/>
      <serviceLink rel="http://opendap.org/rel/dap2/dds"
                   type="application/vnd.opendap.org.dap2.dds"
                   href="http://server/dap/path/data.nc.dds"/>
      <serviceLink rel="http://opendap.org/rel/dap2/ddx"
                   type="application/vnd.opendap.org.dap2.ddx+xml"
                   href="http://server/dap/path/data.nc.ddx"/>
      <serviceLink rel="http://opendap.org/rel/dap2/dods"
                   type="application/vnd.opendap.org.dap2.dods,
                         application/vnd.opendap.org.dap2.dods+ascii"
                   href="http://server/dap/path/data.nc.dods"/>
      <constraintExp ...>...</constraintExp>
      <processing ...>...</processing>
    </version>
    <version name="dap4">
      <serviceLink rel="http://opendap.org/rel/dap4/description"
                   type="application/vnd.opendap.org.dap4.description+xml,
                         application/vnd.opendap.org.dap4.description+json,
                         application/vnd.opendap.org.dap4.description+pbuf"
                   href="http://server/dap/path/data.nc.ddx4"/>
      <serviceLink rel="http://opendap.org/rel/dap4/data"
                   type="application/vnd.opendap.org.dap4.data,
                         application/vnd.opendap.org.dap4.data+ascii,
                         application/vnd.opendap.org.dap4.data+json,
                         application/vnd.opendap.org.dap4.data+ncstream"
                   href="http://server/dap/path/data.nc.data">
        <constraintExp...>...</constraintExp>
        <processing ...>...</processing>
      </serviceLink>
    </version>
  </dataset>
</capabilities>

7.2 Some References