DAP4 Web Services - StartingPoint

From OPeNDAP Documentation
Revision as of 18:10, 30 March 2012 by Ndp (talk | contribs) (Services)

1 Protocol Independence

Proposal: The DAP4 data model and it's persistent (over-the-wire) representations are transport protocol agnostic. All of the information required by the DAP must be present in the content of the DAP requests and responses. The DAP won't uniquely embed information required by the DAP into HTTP Headers or AMQP thingys, or other whatnot.

Discussion:

  1. Does this matter? Is it something to strive for? Is it a Must? Is this just noise??
  2. Can the clients really make a request that's protocol independent?
  3. Would we need to add new syntax server-side functions etc. to the protocol to enable this?

2 Overview

This page describes the various web services that a DAP4 server must provide. These are for the most part REST services and as such are stateless unless noted otherwise.

The services are all defined as a modification of the service (aka resource or base) URL. This base URL essentially becomes a prefix (and could even be seen as a namespace) for all of the services available for that data resource.

In practice these have traditionally been implemented over HTTP. However they could just as easily be pushed over a different protocol, as long as the usage of the URL components remain consistent.

3 Required Responses

3.1 Dataset: The metadata

The Dataset response is an XML document containing a dap:Dataset object as it's root element. It contains the persistent DAP4: Data Model representation of the dataset held at the server. If a constraint expression has been successfully applied, the service will returned the constrained view of the dap:Dataset object. The constrained view may contain different data structures than the unconstrained view as the constraint may alter the reasonable representation of the data set.

Also: All dap:Attribute objects have been removed from constrained dap:Dataset objects.

More information on the Dataset response can be found on the DAP4: Responses page.

More information on the syntax of DAP4 constraint expressions can be found on DAP4: Data Model page.


The standard URL for this response is:

baseURL + '.xml' + [?dap_constraint]

3.2 Data: The data response for the dataset.

A Data response is the way DAP4 returns data to a client. Each Data response is returned over the wire as a multipart MIME document where the first MIME part contains the constrained Dataset response describing the data requested and the following MIME parts contain the data values, encoded using XDR, followed by a checksum, for each variable in the dataset.

More information on the Data response can be found on the DAP4: Responses page.

The standard URL for this response is:

baseURL + '.dap' + [?dap_constraint]

3.3 Service Description

The base URL for a data set accessed through a DAP4 web server will return a service document that describes the various responses possible for that data set, including URLs that can be used to access those responses.

More information on the Service Description response can be found on the DAP Service Terminus page.


The standard URL for this response is:

baseURL

3.4 Error

TBD

4 Services

A Service is simply a name, a URL, and an optional description. A service is accessed by dereferencing its URL, which is typically constructed by adding some type of suffix to the dataset's referent (aka base) URL. The way in which the query string (aka constraint expression) is used is defined by each service, and there is no requirement for inter-service query string API conformity.



4.1 DAP4: Dataset Services Service

Returns a listing of the services available for a particular dataset. Services accept requests in the form of a URL. They may accept query strings (Constraint Expressions). They respond with some type of specific response object. This may include, but is not limited to, any combination of the services that follow.


service url = dataset_url
service id = http://services.opendap.org/dap4/ServiceTerminus#

4.2 DAP4: Dataset Service

The Dataset Service provides a metadata description for a dataset. The Dataset response is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset The dataset service accepts a query string (constraint expression) that allows you to inspect the effects on the data structures when sub-setting and/or server side functions are applied.


suffix = .xml
service url = dataset_url + .xml
service id = http://services.opendap.org/dap4/Dataset#

4.3 DAP4: Data Service

The Data Service provides DAP4 data access to a dataset. The Data response is a multipart MIME document that contains a N+1 parts for a response with N variables. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions.


suffix = .dap
service url = dataset_url + .dap
service id = http://services.opendap.org/dap4/Data#

4.4 DAP4: HTML DATA Request Form Service

The HTML DATA Request Form Service provides browser based access to the Dataset. When invoked it returns a web-browser renderable document (in html) that provides a form (or other UI) that can be used to constrain and request data in accordance with the DAP4 specification as applied to the dataset .


suffix = .html
service url = dataset_url + .html
service id = http://services.opendap.org/dap4/HtmlDataRequestForm#

4.5 DAP4: RDF Service

The RDF service provides an RDF representation of the Dataset document (DDX). The RDF response is an XML document containing an RDF version of the DAP4: Dataset Response.


suffix = .rdf
service url = dataset_url + .rdf
service id = http://services.opendap.org/dap4/Rdf#

4.6 DAP4: ISO 19115 Service

This service provides ISO 19115 metadata for the Dataset, if any can be found. When invoked it returns an XML document containing ISO 19115 metadata located in the DAP4: Dataset Response.


suffix = .iso
service url = dataset_url + .iso
service id = http://services.opendap.org/dap4/Iso19115#

4.7 DAP4: ISO Conformance Rubric Service

This service provides a browser renderable document that describes how well the metadata held in the Dataset conforms to ISO 19115. When invoked this service returns a browser renderable document that describes how well the metadata held in the Dataset Response conforms to ISO 19115.


suffix = .rubric
service url = dataset_url + .rubric
service id = http://services.opendap.org/dap4/Iso19115-Rubric#

4.8 DAP4: NetCDF File-out Service

This service provides data responses in NetCDF-3 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 3 file.

suffix = .nc
service url = dataset_url + .nc
service id = http://services.opendap.org/dap4/NetCDF3#

4.9 DAP4: ASCII Data Service

This service provides data responses in ASCII format. When invoked the regular DAP data response will be repackaged as an ASCII representation of the data values.


suffix = .ascii
service url = dataset_url + .ascii
service id = http://services.opendap.org/dap4/Ascii#

4.10 DAP4: Native File Access Service

This service provides direct access to the data source file (or whatever else) that is creating the DAP dataset resource. When invoked it returns the "native" data from whatever store (filesystem, etc.) it may be in.


suffix = .file
service url = dataset_url + .file
service id = http://services.opendap.org/dap4/File#

4.11 DAP4: Server Version Service

This service provides software versioning information. When invoked the services returns an XML file containing a description of the version of the server and it's components.


suffix = .rdf
service url = dataset_url + .rdf
service id = http://services.opendap.org/dap4/Version#

4.12 DAP2: Data Service

The DAP2 data service provides DAP2 data access to the data resource.


suffix = .dods
service url = dataset_url + .dods
service id = http://services.opendap.org/dap2/Dods#

4.13 DAP2: DDX Service

The DAP2 DDX service provides DAP2 access to the data resource metadata. When invoked the service returns an XML document containing both syntactic and semantic dataset metadata in DAP2 XML format.

suffix = .ddx
service url = dataset_url + .ddx
service id = http://services.opendap.org/dap2/Ddx#

4.14 DAP2: DDS Service

The DAP2 DDS service provides access to the 'syntactic' metadata (aka use or structural metadata) for the data resource. When invoked returns a DAP2 DDS response document conforming to the DDS part of the DAP2 specification.


suffix = .dds
service url = dataset_url + .dds
service id = http://services.opendap.org/dap2/Dds#

4.15 DAP2: DAS Service

The DAP2 DAS service provides access to the 'semantic' metadata (aka domain metadata) for the data resource. When invoked returns a DAP2 DAS response document conforming to the DAS part of the DAP2 specification.


suffix = .das
service url = dataset_url + .das
service id = http://services.opendap.org/dap2/Das#

4.16 DAP2: Info Service

The DAP2 INFO service provides a browser renderable page that combines both the DAP2 'syntactic' and 'semantic' metadata for the data resource in a human readable way. When invoked this service returns a web browser renderable document that combines both the DAP2 'syntactic' and 'semantic' metadata for the data resource in a human readable way.


suffix = .info
service url = dataset_url + .info
service id = http://services.opendap.org/dap2/Info#


Template: ServiceTemplate