DAP4: Capabilities and Versioning
--EthanDavis 13:32, 16 April 2012 (PDT)
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.
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)
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.
Raw DAP Dataset URLs Return Capabilities Documents
http://server.org/some/path/data.nc
A GET request on a DAP dataset URL returns the capabilities document for the dataset. To take advantage of web caching, capabilities Document should try to be light weight (i.e., quick creation) and as stable as possible.
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.
Possible Media Types
- application/vnd.opendap.org.capabilities+xml
- application/vnd.opendap.org.capabilities+json
- application/vnd.opendap.org.capabilities+pbuf
A capabilities resource 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 for all resource types for each supported version
- 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
Other Resource Types
Dataset capabilities documents will include links to the available OPeNDAP services for the dataset. The type of resource at the end of a link will be indicated by the link relation type. The DAP4 core resource types as well as some possible extensions are listed in this section. Details on each resource type are discussed in another section below.
For DAP4, the core set of resource types are:
For DAP2, the core set of resource types are:
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)
Examples
See below.
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.
Discussion
DAP4 Resource Types
DAP4 DDX
DAP4 Data
DAP4 Constraint Expression
DAP4 Processing Instructions
DAP4 Server Capabilities Documents
DAP2 Resource Types
DAP2 DAS
DAP2 DDS
DAP2 DDX
DAP2 Data
DAP2 Constraint Expression
Example Capabilities Document
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>
Some References
- http://stackoverflow.com/a/385216
- Response to the question: Use "Accept" header or extension to identify resource type?
- The ideal would be to implement both.