https://docs.opendap.org/api.php?action=feedcontributions&user=EthanDavis&feedformat=atomOPeNDAP Documentation - User contributions [en]2024-03-29T00:12:35ZUser contributionsMediaWiki 1.38.4https://docs.opendap.org/index.php?title=DAP4_Extension:_Asynchronous_Response&diff=10534DAP4 Extension: Asynchronous Response2014-04-22T16:23:32Z<p>EthanDavis: </p>
<hr />
<div>This document specifies the DAP4 Asynchronous HTTP Response extension. It defines the set of HTTP mechanisms used by DAP4 clients and servers when requesting or delivering asynchronous responses.<br />
<br />
This extension provides DAP4 with a mechanism that allows servers to handle requests where the construction or computation of the response takes more time than a client may wish to wait.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
The Role URI for the DAP4 Asynchronous HTTP Response extension is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/asynchronous-http-response</nowiki>'''<br />
<br />
DAP4 servers MUST include this role URI in a Dataset Service Response [DSR] ''extension'' element to indicate that the DAP4 Asynchronous HTTP Response extension is supported for the dataset (?represented by that DSR?). DAP4 clients MAY check for DSR '''extension''' elements with this role URI to determine if the DAP4 Asynchronous HTTP Response extension is supported.<br />
<br />
Dataset Service Response [DSR] ''extension'' elements must also contain a name and a description. The following are recommended text for the name and description:<br />
<br />
;Name<br />
: DAP4 Asynchronous HTTP Response<br />
<br />
;Description <br />
: This extension provides DAP4 with a mechanism to support asynchronous HTTP responses, e.g., when a request will take the server time to fulfill.<br />
<br />
== Summary of HTTP Mechanisms Used to Support Asynchronous HTTP Response ==<br />
<br />
Role: http://services.opendap.org/dap4/async<br />
<br />
Response:<br />
<br />
* DAP4 Asynch Response document:<br />
** Media Type: application/vnd.opendap.dap4.async+xml<br />
** XML Namespace: http://opendap.org/ns/dap/asynchronous<br />
** Types of documents<br />
*** Required<br />
*** Accepted<br />
*** Not Yet Available<br />
*** Gone<br />
<br />
HTTP Request Headers<br />
<br />
HTTP Response Headers<br />
<br />
URL Query String: dap4.async<br />
<br />
== Overview: Asynchronous Service Behavior and Responses ==<br />
Asynchronous responses are responses that will take the server some time to build. When a client is told that a response 'is asynchronous,' it must know to come back at a later time to retrieve the response. The concept is a very simple one, and the existing network infrastructure is very good at supporting these kinds of interactions. A major factor in the success of the proposed solution will be the level of uniform support for the design. Secondly, as is often the case, the details will be more complex than the underlying concept. In particular, the request mechanism must be extended so that synchronous (regular) requests are not affected by the addition of asynchronous requests and, at the same time, clients do not inadvertently make asynchronous requests. another detail is that the (asynchronous) responses are ''ephemeral'' because they typically only persist for a period of time and then be purged.<br />
<br />
A typical 'workflow' for an asynchronous request is:<br />
# A client makes a data request that indicates that it will accept either an asynchronous or synchronous response. Optionally, the client can place a time constraint on the response, indicating that if the response will not be ready in a given period of time, it does not want the response.<br />
# The server returns an initial response (without delay) that indicates the request has indeed resulted in an asynchronous response and provides the client with a URL and time estimate. <br />
# The client reads the time estimate and waits...<br />
# The client dereferences the URL and gets the response.<br />
<br />
; Examples<br />
: A DAP4 server that is retrieving data content from a near-line tape storage subsystem might take several minutes to access a particular data holding. <br />
: A DAP4 server that is providing access to data held in an Amazon Web Services Glacier Vault will have to wait ~4 hours before it can retrieve a particular holding. <br />
In these circumstances the server may return the DAP4 Asynchronous Response.<br />
<br />
The remainder of this section will expand on this basic workflow using examples that focus on the HTTP protocol but that also allow for the use of other transport protocols.<br />
<br />
== Client willingness to accept asynchronous responses ==<br />
A client can indicate willingness to accept asynchronous responses in one of two ways:<br />
* By including the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header.<br />
* By adding the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword to the DAP constraint expression.<br />
<br />
If the client indicates that it must have access to the asynchronous response content within a certain time (utilizing either the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header and/or the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword in the constraint expression) and the response will not be available in that time frame, the server MUST reject the request and return an HTTP status of [[#412_Precondition_Failed | 412]] and the [[#DAP Asynchronous Request Rejected | DAP Asynchronous Request Rejected]] XML document.<br />
<br />
If both the ''X-DAP-Async-Accept'' HTTP header and the ''async'' keyword are used, the keyword takes precedence.<br />
<br />
Servers must reject requests that require an asynchronous response if the client has not indicated willingness to accept such a response. Rejection of such requests is indicated by all three of the following:<br />
# [[#400 DAP Asynchronous Response Required| HTTP status of 400]]<br />
# Inclusion of the [[#DAP Asynchronous Response Required|X-DAP-Async-Required]] HTTP response header<br />
# The response body must contain the [[#DAP_Asynchronous_Response_Required | DAP Asynchronous Response Required]] XML document. <br />
This safety check (requiring clients to explicitly indicate their willingness to accept asynchronous responses) is required because otherwise very simple clients might inadvertently make requests that will result in an asynchronous responses, and these kinds of responses are likely to use disproportionately (relative to synchronous responses) more server resources. We want to make DAP4 so that simple clients work well and don't encounter unexpected 'hiccups.'<br />
<br />
== Initial processing by the server ==<br />
When a request is accepted by the server and it will result in an asynchronous response, the server MUST the server MUST return a 202 (Accepted) HTTP<br />
status code and the [[#DAP Asynchronous Request Accepted | DAP Asynchronous Request Accepted ]] XML document. This document contains a URL to the pending result of the request.<br />
<br />
Of course, this discussion is about the mechanism that enables a client to make a request and the server to provide ''information about'' an asynchronous response to that request. It does not cover any of the nearly infinite ways a server might actually make the ''content'' of that response. It is likely that servers will write the responses to files and the URL returned to the client will be used to retrieve that file, but there's no requirement that servers do that. The only requirements on server are that:<br />
#The URL returned asserts, using the [[#DAP4_Constraint_Expression_extension_for_Async | constraint expression syntax for async]] that the client accepts async responses.<br />
# The URL returned can be dereferenced and that operation will return the response requested by the client.<br />
<br />
== Response retrieval by the client ==<br />
When a client requests an asynchronous result that is ready, the server MUST return a 200 (OK) HTTP status code and the resulting data response. If the client attempts to access the asynchronous result prior to it's availability, the server SHOULD return an HTTP response status of [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 (DAP Response Not Ready)]] along with the [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP Asynchronous Response Not Available]] XML document. If the server does not return the 409 response status then it MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
If the client attempts to access the asynchronous result after it is no longer available, the server SHOULD return an [[#410_Gone_-_DAP4_Response_No_Longer_Available | HTTP response status of 410 (Gone)]] along with the [[#DAP4_Asynchronous_Response_Gone| DAP4 Asynchronous Response Gone]] document. If the server does not return the 410 response status then the server MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
In each case above where the server SHOULD return a specific error code, but may return a 404 code instead, the intent is for servers to provide the most appropriate use of HTTP/1.1's error codes while also providing servers with an 'out' when that is hard for them to do. For example, knowing that a response, which is essentially ephemeral, is gone would, in theory, require to server to keep a record of every URL ever issued for an asynchronous response and that is not practical. At the same time, it is easy to see that a client would really like to know that the response has not yet been finished (i.e., it has not waited long enough) or that it is gone (i.e., it waited too long).<br />
<br />
== Detail: Client requests ==<br />
<br />
=== DAP4 Constraint Expression extension for Async ===<br />
By adding a keyword/value pair to the DAP4 query string we can allow a client to encode it's willingness to accept an asynchronous response, along with the a maximum amount of time the client can wait before it can access the response. <br />
<br />
; dap4.async<br />
: A value of zero indicates the client is willing to unconditionally accept an asynchronous response. A positive integer value will be interpreted as the number of seconds that the client will wait for access to the response. If the value is negative the serve MUST return an error. <br />
<br />
; Examples<br />
: Client is willing to unconditionally accept an asynchronous response<br />
:: <code>?dap4.async=0</code><br />
: Client is willing to wait for 60 seconds for access to the asynchronous response<br />
:: <code>?dap4.async=60</code><br />
<br />
=== X-DAP-Async-Accept ===<br />
<br />
A client may indicate willingness to accept asynchronous responses by including the ''X-DAP-Async-Accept'' HTTP header. Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
== Detail: Server responses ==<br />
<br />
Several 'experimental' HTTP headers are used by this design. They convey information either in the request (like the ''X-DAP-Async-Accept'' described above) or they encode information for a response. While only clients that intend to support asynchronous responses need to understand all of these, ''every'' client SHOULD understand the ''X-DAP-Async-Required'' header. Because we need to support clients like web browsers, knowledge of that header is not required, but DAP4-specific clients will provide the most information to users if they know to look for at least that response header.<br />
<br />
=== HTTP Response Headers ===<br />
==== X-DAP-Async-Required ====<br />
<br />
The ''X-DAP-Async-Required'' HTTP response header is included in the response if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[#400_DAP4_Asynchronous_Response_Required |400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
==== X-DAP-Async-Accepted ====<br />
<br />
The ''X-DAP-Async-Accepted'' HTTP response header is included in the response if the server has accepted an asynchronous request. Acceptance of the request should also be indicated by the [[#202_Accepted|202 Asynchronous Request Accepted]] HTTP response code.<br />
<br />
=== HTTP Response Codes ===<br />
<br />
HTTP provides a number of response codes beyond the simple 200 (OK), 404 (Not Found) and 500 (Internal Server Error). In this design we describe how those standard codes SHOULD be used by DAP4 servers. We don't enumerate all of the possible codes, instead opting for a description of those that most relevant.<br />
<br />
==== 202 Accepted ====<br />
<br />
A server indicates that a request has been accepted and will be handled asynchronously by returning a '202 Accepted' HTTP response code. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types|below]]. A server MUST return this response, and only do so, when a client has indicated a willingness to process an asynchronous response and the response will actually be returned using the asynchronous mechanism.<br />
<br />
==== 400 DAP4 Asynchronous Response Required ====<br />
<br />
The '400 DAP Asynchronous Response Required' HTTP response code is used to indicate that the DAP4 request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response.<br />
<br />
The response code text is used to indicate the reason for the rejection. However, since the '400' HTTP response code is not specific to asynchronous DAP (the standard text for the '400' code is "Bad Request"), the ''X-DAP-Async-Required'' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response|above]]).<br />
<br />
'''Note''' that a standard 400 HTTP response code is returned. In this way, a client that does not understand asynchronous DAP can fail gracefully. The response code text message has been changed to be more informative of the reason for the failure. For clients that are aware of asynchronous DAP, the "DAP-Async-Required" header is set to "true". The body of the response also returns some information the client can use to decide on how it will continue.<br />
<br />
==== 409 Conflict - DAP4 Response Not Ready ====<br />
<br />
The '409 Conflict' HTTP response code MAY be returned by a server to indicate that the DA4P request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. If a server utilizes the '409 Conflict' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document in the response body.<br />
<br />
==== 410 Gone - DAP4 Response No Longer Available ====<br />
<br />
The '410 Gone' HTTP response code MAY be used by a server to indicate that the result of an asynchronous request is no longer available. If a server utilizes the '410 Gone' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Gone | DAP4 Asynchronous Response Gone]] document in the response body.<br />
<br />
==== 412 Precondition Failed====<br />
<br />
The '412 Precondition Failed' HTTP response code is used to indicate that the DAP request has been rejected because it did not meet the '''X-DAP-Async-Accept''' condition (see [[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion|above]]) that was specified in the request.<br />
<br />
==== 500 Internal Error====<br />
<br />
The '500 Internal Error' HTTP response code is used to indicate that the DAP request has caused an error on the server. The request body and other headers must be compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
=== Asynchronous Response Documents ===<br />
<br />
The uses of these documents are:<br />
* to inform clients that a request will result in an asynchronous response;<br />
* to provide clients with the status of an an accepted asynchronous request; and<br />
* to inform clients that a request for and asynchronous response has been rejected.<br />
<br />
These response documents are the payloads to various responses, including errors. By using the HTTP 400-series error response codes, the design ensures that generic web clients will understand that their request was in error (even if they don't really understand why). The text provided with the response code will be sufficient that person could understand the gist of the problem, if not more. The response documents described here, along with the ''X-DAP'' describe above, are a way of providing additional information to a savvy client so that it can take full advantage of the synchronous response system.<br />
<br />
These documents are XML that follows the DAP Asynchronous XML schema and are declared in the namespace '''<nowiki>http://opendap.org/ns/dap/asynchronous</nowiki>'''.<br />
<br />
==== DAP4 Asynchronous Response Required ====<br />
<br />
This document informs clients that a request will result in an asynchronous response, and that the client has not yet indicated it's willingness to accept an asynchronous response. It might seem superfluous to include a document that clearly only a client knowledgable about the asynchronous response features could parse, but many such clients may not, as a matter of course, indicate they will accept these responses. For example, a user-configurable parameter might be turn off support for the feature. The ''expectedDelay'' and ''responseLifetime'' elements convey information about conditions the clients can expect if it submits an asynchronous request for the response. As noted below, these are estimates made by the server since a number of things that the server cannot predict can affect them in the interleaving time between the client's requests. Additionally, a server MAY return values of zero for either of the values, indicating that it cannot make an accurate estimate.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response MUST be associated with the 400 HTTP response code and the ''X-DAP-Async-Required'' response header.<br />
<br />
==== DAP4 Asynchronous Request Accepted ====<br />
<br />
This response informs clients that a request resulting in an asynchronous response has been accepted, along with operational information about retrieving the asynchronous response result. Note that the ''expectedDelay'' and ''responseLifetime'' elements are an estimate by the server. A server SHOULD ensure that the response will remain available for the time period given by ''expectedDelay'' and ''responseLifetime''. We say ''SHOULD'' and not ''MUST'' because we cannot predict all possible operational situations where these kinds of responses might be used. For example, a server might be providing access for several types of users who might have different access priorities, especially to limited resources like those typically involved with asynchronous access, and thus some responses might be further delayed, or removed early, to enable processing of requests from users with higher priority. It should be kept in mind, however, that the usefulness of the asynchronous responses will depend, in part, on servers providing a facility on which clients can depend.<br />
<br />
While the ''expectedDelay'' and ''responseLifetime'' elements are required, a server MAY set their ''seconds'' attribute to ''0'' to indicate that it cannot provide a reliable value. In this case, clients SHOULD poll every 300 seconds and servers SHOULD expect this behavior. This is the default TCP user timeout period (see http://tools.ietf.org/html/rfc5482).<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response document MUST be associated with the 202 HTTP status code and the ''X-DAP-Async-Accepted'' response header.<br />
<br />
==== DAP4 Asynchronous Response Not (Yet) Available ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is not available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="pending"/><br />
</source><br />
This response document MUST be associated with the [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 HTTP response code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 409, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Response Gone ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is ''no longer'' available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="gone"/><br />
</source><br />
This response document MUST be associated with the [[#410_Gone_-_DAP4_Response_No_Longer_Available| 410 HTTP status code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 410, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Request Rejected ====<br />
<br />
This document informs clients that a request for an asynchronous response has been rejected, even though the client said it is willing to process an asynchronous response. There are at least as many reasons a server might reject the request for an asynchronous response as there are systems that might return such responses. However, this design provides suggested response codes for cases that seem likely so that clients can make educated decisions about the reason for the rejection. The reason codes supported are:<br />
;time: The client indicated that it was only willing to wait ''X'' seconds and the server thought it would take more time to build the result.<br />
;unavailable: A needed resource is not available. This might indicate that hardware, like a robot tape system, cannot be currently accessed.<br />
;privileges: The client is not allowed to make the request. <br />
;other: Self evident...<br />
In addition to the reason codes, this response will contain a text description of the reason for rejection.<br />
<br />
Servers SHOULD make every effort to use the correct reason codes and provide cogent descriptions.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
This response document MUST associated with the 412 HTTP status code. <br />
<br />
Servers SHOULD return this response document along with an HTTP status of 412, but servers MAY return any document in the response body along with an HTTP status of 404 (Not Found) or of 400 (Bad Request) in its place.<br />
<br />
==== DAP4 Error ====<br />
<br />
If the server encounters an error it must MUST (MAY?) return an HTTP status of 500 (Internal Error) along with a request body and other headers compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
== Examples ==<br />
<br />
=== Constrained Data Request-Response using GET ===<br />
<br />
; Simple Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
If the server decides it needs to handle this request in an asynchronous manner, it will refuse the request because it did not say it would accept an asynchronous response.<br />
<br />
; Response:<br />
<source lang="xml"><br />
400 DAP Asynchronous Response Required<br />
X-DAP-Async-Required: true<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 0<br />
<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=0&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
202 Accepted<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
'''NB''': This example originally included an ''Accept'' header with the value of ''multipart/mixed''. However, that is not a good example. The HTTP/1.1 specification says that when a specific media type is indicated as the only one acceptable, a server must return a 406 response code if it cannot return that media type. The meaning of ''Accept: */*'' is the same as not including the header, so I have removed the header from these examples. We need to be heads up in the ways that we suggest that header should be used by clients<br />
<br />
=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 60<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=60&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
412 Precondition Failed<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Premature Request For Asynchronous Result ===<br />
<br />
Request:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
<br />
Response:<br />
<source lang="xml"><br />
409 Conflict<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="pending"/><br />
</source><br />
<br />
== Resource Role ==<br />
<br />
DAP4 Asynchronous Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/async</nowiki></code></font>'''<br />
<br />
== Normative Encoding of the Asynchronous Response ==<br />
<br />
The normative XML representation for the Asynchronous Response is defined in Appendix x "Normative XML Encoding of the Asynchronous Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.dap4.async.xml'''</code></font></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10533DAP4 Extension: CSV Data Encoding and Response2014-04-22T16:23:10Z<p>EthanDavis: /* DAP4 Extension Details */</p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This document specifies the DAP4 CSV data encoding, how DAP4 servers can advertise support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses.<br />
<br />
The DAP4 CSV data encoding represents DAP4 data as structured Comma-Separated Values (CSV) in UTF-8 text. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can fully represent the more complex data structures of the DAP4 data model. Some structure beyond simple CSV is necessary to capture the DAP4 data structures.<br />
<br />
As with requests for data in the DAP4 binary data encoding described in Volume 1 of the DAP4 specification <sup><nowiki>[</nowiki>[[#DAP4_Vol1|DAP4 Vol1]]<nowiki>]</nowiki></sup>, requests for DAP4 CSV encoded data can be constrained to a subset by using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
== DAP4 Extension Details ==<br />
<br />
The Role URI for the DAP4 CSV Data Encoding and Response extension is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/text-csv-data</nowiki>'''<br />
<br />
DAP4 servers MUST include this role URI in a Dataset Service Response [DSR] ''extension'' element to indicate that the DAP4 CSV Data Encoding and Response extension is supported for the dataset (?represented by that DSR?). DAP4 clients MAY check for DSR '''extension''' elements with this role URI to determine if the DAP4 CSV Data Encoding and Response extension is supported.<br />
<br />
Dataset Service Response [DSR] ''extension'' elements must also contain a name and a description. The following are recommended text for the name and description:<br />
<br />
<br />
;Name<br />
: DAP4 CSV Data Encoding and Response<br />
<br />
;Description <br />
: This extension provides an encoding for representing DAP4 data as structured Comma-Separated Values (CSV) in UTF-8 text.<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_Asynchronous_Response&diff=10532DAP4 Extension: Asynchronous Response2014-04-22T05:33:50Z<p>EthanDavis: </p>
<hr />
<div>This document specifies the DAP4 Asynchronous HTTP Response extension. Its main focus is on defining the set of HTTP mechanisms used by DAP4 clients and servers when requesting or delivering asynchronous responses.<br />
<br />
The DAP4 Asynchronous HTTP Response extension provides DAP4 with a mechanism that allows servers to handle requests where the construction or computation of the response takes more time than a client may wish to wait.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
The Role URI for the DAP4 Asynchronous HTTP Response extension is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/asynchronous-http-response</nowiki>'''<br />
<br />
DAP4 servers MUST include this role URI in a Dataset Service Response [DSR] ''extension'' element to indicate that the DAP4 Asynchronous HTTP Response extension is supported for the dataset (?represented by that DSR?). DAP4 clients MAY check for DSR '''extension''' elements with this role URI to determine if the DAP4 Asynchronous HTTP Response extension is supported.<br />
<br />
Dataset Service Response [DSR] ''extension'' elements must also contain a name and a description. The following are recommended text for the name and description:<br />
<br />
;Name<br />
: DAP4 Asynchronous HTTP Response<br />
<br />
;Description <br />
: Extension that defines how DAP4 supports asynchronous HTTP responses, e.g., when a request will take the server time to fulfill.<br />
<br />
== Summary of HTTP Mechanisms Used to Support Asynchronous HTTP Response ==<br />
<br />
Role: http://services.opendap.org/dap4/async<br />
<br />
Response:<br />
<br />
* DAP4 Asynch Response document:<br />
** Media Type: application/vnd.opendap.dap4.async+xml<br />
** XML Namespace: http://opendap.org/ns/dap/asynchronous<br />
** Types of documents<br />
*** Required<br />
*** Accepted<br />
*** Not Yet Available<br />
*** Gone<br />
<br />
HTTP Request Headers<br />
<br />
HTTP Response Headers<br />
<br />
URL Query String: dap4.async<br />
<br />
== Overview: Asynchronous Service Behavior and Responses ==<br />
Asynchronous responses are responses that will take the server some time to build. When a client is told that a response 'is asynchronous,' it must know to come back at a later time to retrieve the response. The concept is a very simple one, and the existing network infrastructure is very good at supporting these kinds of interactions. A major factor in the success of the proposed solution will be the level of uniform support for the design. Secondly, as is often the case, the details will be more complex than the underlying concept. In particular, the request mechanism must be extended so that synchronous (regular) requests are not affected by the addition of asynchronous requests and, at the same time, clients do not inadvertently make asynchronous requests. another detail is that the (asynchronous) responses are ''ephemeral'' because they typically only persist for a period of time and then be purged.<br />
<br />
A typical 'workflow' for an asynchronous request is:<br />
# A client makes a data request that indicates that it will accept either an asynchronous or synchronous response. Optionally, the client can place a time constraint on the response, indicating that if the response will not be ready in a given period of time, it does not want the response.<br />
# The server returns an initial response (without delay) that indicates the request has indeed resulted in an asynchronous response and provides the client with a URL and time estimate. <br />
# The client reads the time estimate and waits...<br />
# The client dereferences the URL and gets the response.<br />
<br />
; Examples<br />
: A DAP4 server that is retrieving data content from a near-line tape storage subsystem might take several minutes to access a particular data holding. <br />
: A DAP4 server that is providing access to data held in an Amazon Web Services Glacier Vault will have to wait ~4 hours before it can retrieve a particular holding. <br />
In these circumstances the server may return the DAP4 Asynchronous Response.<br />
<br />
The remainder of this section will expand on this basic workflow using examples that focus on the HTTP protocol but that also allow for the use of other transport protocols.<br />
<br />
== Client willingness to accept asynchronous responses ==<br />
A client can indicate willingness to accept asynchronous responses in one of two ways:<br />
* By including the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header.<br />
* By adding the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword to the DAP constraint expression.<br />
<br />
If the client indicates that it must have access to the asynchronous response content within a certain time (utilizing either the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header and/or the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword in the constraint expression) and the response will not be available in that time frame, the server MUST reject the request and return an HTTP status of [[#412_Precondition_Failed | 412]] and the [[#DAP Asynchronous Request Rejected | DAP Asynchronous Request Rejected]] XML document.<br />
<br />
If both the ''X-DAP-Async-Accept'' HTTP header and the ''async'' keyword are used, the keyword takes precedence.<br />
<br />
Servers must reject requests that require an asynchronous response if the client has not indicated willingness to accept such a response. Rejection of such requests is indicated by all three of the following:<br />
# [[#400 DAP Asynchronous Response Required| HTTP status of 400]]<br />
# Inclusion of the [[#DAP Asynchronous Response Required|X-DAP-Async-Required]] HTTP response header<br />
# The response body must contain the [[#DAP_Asynchronous_Response_Required | DAP Asynchronous Response Required]] XML document. <br />
This safety check (requiring clients to explicitly indicate their willingness to accept asynchronous responses) is required because otherwise very simple clients might inadvertently make requests that will result in an asynchronous responses, and these kinds of responses are likely to use disproportionately (relative to synchronous responses) more server resources. We want to make DAP4 so that simple clients work well and don't encounter unexpected 'hiccups.'<br />
<br />
== Initial processing by the server ==<br />
When a request is accepted by the server and it will result in an asynchronous response, the server MUST the server MUST return a 202 (Accepted) HTTP<br />
status code and the [[#DAP Asynchronous Request Accepted | DAP Asynchronous Request Accepted ]] XML document. This document contains a URL to the pending result of the request.<br />
<br />
Of course, this discussion is about the mechanism that enables a client to make a request and the server to provide ''information about'' an asynchronous response to that request. It does not cover any of the nearly infinite ways a server might actually make the ''content'' of that response. It is likely that servers will write the responses to files and the URL returned to the client will be used to retrieve that file, but there's no requirement that servers do that. The only requirements on server are that:<br />
#The URL returned asserts, using the [[#DAP4_Constraint_Expression_extension_for_Async | constraint expression syntax for async]] that the client accepts async responses.<br />
# The URL returned can be dereferenced and that operation will return the response requested by the client.<br />
<br />
== Response retrieval by the client ==<br />
When a client requests an asynchronous result that is ready, the server MUST return a 200 (OK) HTTP status code and the resulting data response. If the client attempts to access the asynchronous result prior to it's availability, the server SHOULD return an HTTP response status of [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 (DAP Response Not Ready)]] along with the [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP Asynchronous Response Not Available]] XML document. If the server does not return the 409 response status then it MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
If the client attempts to access the asynchronous result after it is no longer available, the server SHOULD return an [[#410_Gone_-_DAP4_Response_No_Longer_Available | HTTP response status of 410 (Gone)]] along with the [[#DAP4_Asynchronous_Response_Gone| DAP4 Asynchronous Response Gone]] document. If the server does not return the 410 response status then the server MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
In each case above where the server SHOULD return a specific error code, but may return a 404 code instead, the intent is for servers to provide the most appropriate use of HTTP/1.1's error codes while also providing servers with an 'out' when that is hard for them to do. For example, knowing that a response, which is essentially ephemeral, is gone would, in theory, require to server to keep a record of every URL ever issued for an asynchronous response and that is not practical. At the same time, it is easy to see that a client would really like to know that the response has not yet been finished (i.e., it has not waited long enough) or that it is gone (i.e., it waited too long).<br />
<br />
== Detail: Client requests ==<br />
<br />
=== DAP4 Constraint Expression extension for Async ===<br />
By adding a keyword/value pair to the DAP4 query string we can allow a client to encode it's willingness to accept an asynchronous response, along with the a maximum amount of time the client can wait before it can access the response. <br />
<br />
; dap4.async<br />
: A value of zero indicates the client is willing to unconditionally accept an asynchronous response. A positive integer value will be interpreted as the number of seconds that the client will wait for access to the response. If the value is negative the serve MUST return an error. <br />
<br />
; Examples<br />
: Client is willing to unconditionally accept an asynchronous response<br />
:: <code>?dap4.async=0</code><br />
: Client is willing to wait for 60 seconds for access to the asynchronous response<br />
:: <code>?dap4.async=60</code><br />
<br />
=== X-DAP-Async-Accept ===<br />
<br />
A client may indicate willingness to accept asynchronous responses by including the ''X-DAP-Async-Accept'' HTTP header. Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
== Detail: Server responses ==<br />
<br />
Several 'experimental' HTTP headers are used by this design. They convey information either in the request (like the ''X-DAP-Async-Accept'' described above) or they encode information for a response. While only clients that intend to support asynchronous responses need to understand all of these, ''every'' client SHOULD understand the ''X-DAP-Async-Required'' header. Because we need to support clients like web browsers, knowledge of that header is not required, but DAP4-specific clients will provide the most information to users if they know to look for at least that response header.<br />
<br />
=== HTTP Response Headers ===<br />
==== X-DAP-Async-Required ====<br />
<br />
The ''X-DAP-Async-Required'' HTTP response header is included in the response if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[#400_DAP4_Asynchronous_Response_Required |400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
==== X-DAP-Async-Accepted ====<br />
<br />
The ''X-DAP-Async-Accepted'' HTTP response header is included in the response if the server has accepted an asynchronous request. Acceptance of the request should also be indicated by the [[#202_Accepted|202 Asynchronous Request Accepted]] HTTP response code.<br />
<br />
=== HTTP Response Codes ===<br />
<br />
HTTP provides a number of response codes beyond the simple 200 (OK), 404 (Not Found) and 500 (Internal Server Error). In this design we describe how those standard codes SHOULD be used by DAP4 servers. We don't enumerate all of the possible codes, instead opting for a description of those that most relevant.<br />
<br />
==== 202 Accepted ====<br />
<br />
A server indicates that a request has been accepted and will be handled asynchronously by returning a '202 Accepted' HTTP response code. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types|below]]. A server MUST return this response, and only do so, when a client has indicated a willingness to process an asynchronous response and the response will actually be returned using the asynchronous mechanism.<br />
<br />
==== 400 DAP4 Asynchronous Response Required ====<br />
<br />
The '400 DAP Asynchronous Response Required' HTTP response code is used to indicate that the DAP4 request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response.<br />
<br />
The response code text is used to indicate the reason for the rejection. However, since the '400' HTTP response code is not specific to asynchronous DAP (the standard text for the '400' code is "Bad Request"), the ''X-DAP-Async-Required'' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response|above]]).<br />
<br />
'''Note''' that a standard 400 HTTP response code is returned. In this way, a client that does not understand asynchronous DAP can fail gracefully. The response code text message has been changed to be more informative of the reason for the failure. For clients that are aware of asynchronous DAP, the "DAP-Async-Required" header is set to "true". The body of the response also returns some information the client can use to decide on how it will continue.<br />
<br />
==== 409 Conflict - DAP4 Response Not Ready ====<br />
<br />
The '409 Conflict' HTTP response code MAY be returned by a server to indicate that the DA4P request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. If a server utilizes the '409 Conflict' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document in the response body.<br />
<br />
==== 410 Gone - DAP4 Response No Longer Available ====<br />
<br />
The '410 Gone' HTTP response code MAY be used by a server to indicate that the result of an asynchronous request is no longer available. If a server utilizes the '410 Gone' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Gone | DAP4 Asynchronous Response Gone]] document in the response body.<br />
<br />
==== 412 Precondition Failed====<br />
<br />
The '412 Precondition Failed' HTTP response code is used to indicate that the DAP request has been rejected because it did not meet the '''X-DAP-Async-Accept''' condition (see [[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion|above]]) that was specified in the request.<br />
<br />
==== 500 Internal Error====<br />
<br />
The '500 Internal Error' HTTP response code is used to indicate that the DAP request has caused an error on the server. The request body and other headers must be compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
=== Asynchronous Response Documents ===<br />
<br />
The uses of these documents are:<br />
* to inform clients that a request will result in an asynchronous response;<br />
* to provide clients with the status of an an accepted asynchronous request; and<br />
* to inform clients that a request for and asynchronous response has been rejected.<br />
<br />
These response documents are the payloads to various responses, including errors. By using the HTTP 400-series error response codes, the design ensures that generic web clients will understand that their request was in error (even if they don't really understand why). The text provided with the response code will be sufficient that person could understand the gist of the problem, if not more. The response documents described here, along with the ''X-DAP'' describe above, are a way of providing additional information to a savvy client so that it can take full advantage of the synchronous response system.<br />
<br />
These documents are XML that follows the DAP Asynchronous XML schema and are declared in the namespace '''<nowiki>http://opendap.org/ns/dap/asynchronous</nowiki>'''.<br />
<br />
==== DAP4 Asynchronous Response Required ====<br />
<br />
This document informs clients that a request will result in an asynchronous response, and that the client has not yet indicated it's willingness to accept an asynchronous response. It might seem superfluous to include a document that clearly only a client knowledgable about the asynchronous response features could parse, but many such clients may not, as a matter of course, indicate they will accept these responses. For example, a user-configurable parameter might be turn off support for the feature. The ''expectedDelay'' and ''responseLifetime'' elements convey information about conditions the clients can expect if it submits an asynchronous request for the response. As noted below, these are estimates made by the server since a number of things that the server cannot predict can affect them in the interleaving time between the client's requests. Additionally, a server MAY return values of zero for either of the values, indicating that it cannot make an accurate estimate.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response MUST be associated with the 400 HTTP response code and the ''X-DAP-Async-Required'' response header.<br />
<br />
==== DAP4 Asynchronous Request Accepted ====<br />
<br />
This response informs clients that a request resulting in an asynchronous response has been accepted, along with operational information about retrieving the asynchronous response result. Note that the ''expectedDelay'' and ''responseLifetime'' elements are an estimate by the server. A server SHOULD ensure that the response will remain available for the time period given by ''expectedDelay'' and ''responseLifetime''. We say ''SHOULD'' and not ''MUST'' because we cannot predict all possible operational situations where these kinds of responses might be used. For example, a server might be providing access for several types of users who might have different access priorities, especially to limited resources like those typically involved with asynchronous access, and thus some responses might be further delayed, or removed early, to enable processing of requests from users with higher priority. It should be kept in mind, however, that the usefulness of the asynchronous responses will depend, in part, on servers providing a facility on which clients can depend.<br />
<br />
While the ''expectedDelay'' and ''responseLifetime'' elements are required, a server MAY set their ''seconds'' attribute to ''0'' to indicate that it cannot provide a reliable value. In this case, clients SHOULD poll every 300 seconds and servers SHOULD expect this behavior. This is the default TCP user timeout period (see http://tools.ietf.org/html/rfc5482).<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response document MUST be associated with the 202 HTTP status code and the ''X-DAP-Async-Accepted'' response header.<br />
<br />
==== DAP4 Asynchronous Response Not (Yet) Available ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is not available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="pending"/><br />
</source><br />
This response document MUST be associated with the [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 HTTP response code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 409, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Response Gone ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is ''no longer'' available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="gone"/><br />
</source><br />
This response document MUST be associated with the [[#410_Gone_-_DAP4_Response_No_Longer_Available| 410 HTTP status code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 410, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Request Rejected ====<br />
<br />
This document informs clients that a request for an asynchronous response has been rejected, even though the client said it is willing to process an asynchronous response. There are at least as many reasons a server might reject the request for an asynchronous response as there are systems that might return such responses. However, this design provides suggested response codes for cases that seem likely so that clients can make educated decisions about the reason for the rejection. The reason codes supported are:<br />
;time: The client indicated that it was only willing to wait ''X'' seconds and the server thought it would take more time to build the result.<br />
;unavailable: A needed resource is not available. This might indicate that hardware, like a robot tape system, cannot be currently accessed.<br />
;privileges: The client is not allowed to make the request. <br />
;other: Self evident...<br />
In addition to the reason codes, this response will contain a text description of the reason for rejection.<br />
<br />
Servers SHOULD make every effort to use the correct reason codes and provide cogent descriptions.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
This response document MUST associated with the 412 HTTP status code. <br />
<br />
Servers SHOULD return this response document along with an HTTP status of 412, but servers MAY return any document in the response body along with an HTTP status of 404 (Not Found) or of 400 (Bad Request) in its place.<br />
<br />
==== DAP4 Error ====<br />
<br />
If the server encounters an error it must MUST (MAY?) return an HTTP status of 500 (Internal Error) along with a request body and other headers compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
== Examples ==<br />
<br />
=== Constrained Data Request-Response using GET ===<br />
<br />
; Simple Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
If the server decides it needs to handle this request in an asynchronous manner, it will refuse the request because it did not say it would accept an asynchronous response.<br />
<br />
; Response:<br />
<source lang="xml"><br />
400 DAP Asynchronous Response Required<br />
X-DAP-Async-Required: true<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 0<br />
<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=0&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
202 Accepted<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
'''NB''': This example originally included an ''Accept'' header with the value of ''multipart/mixed''. However, that is not a good example. The HTTP/1.1 specification says that when a specific media type is indicated as the only one acceptable, a server must return a 406 response code if it cannot return that media type. The meaning of ''Accept: */*'' is the same as not including the header, so I have removed the header from these examples. We need to be heads up in the ways that we suggest that header should be used by clients<br />
<br />
=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 60<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=60&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
412 Precondition Failed<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Premature Request For Asynchronous Result ===<br />
<br />
Request:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
<br />
Response:<br />
<source lang="xml"><br />
409 Conflict<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="pending"/><br />
</source><br />
<br />
== Resource Role ==<br />
<br />
DAP4 Asynchronous Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/async</nowiki></code></font>'''<br />
<br />
== Normative Encoding of the Asynchronous Response ==<br />
<br />
The normative XML representation for the Asynchronous Response is defined in Appendix x "Normative XML Encoding of the Asynchronous Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.dap4.async.xml'''</code></font></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_Asynchronous_Response&diff=10531DAP4 Extension: Asynchronous Response2014-04-22T04:42:44Z<p>EthanDavis: </p>
<hr />
<div>== DAP4 Extension Details ==<br />
<br />
The Role URI for the DAP4 Asynchronous Response extension is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/asynchronous-response</nowiki>'''<br />
<br />
DAP4 servers MUST include this role URI in a Dataset Service Response [DSR] ''extension'' element to indicate that the DAP4 Asynchronous Response extension is supported for the dataset (?represented by that DSR?). DAP4 clients MAY check for DSR '''extension''' elements with this role URI to determine if the DAP4 Asynchronous Response extension is supported.<br />
<br />
Dataset Service Response [DSR] ''extension'' elements must also contain a name and a description. The following are recommended text for the name and description:<br />
<br />
;Name<br />
: DAP4 Asynchronous Response<br />
<br />
;Description <br />
: Extension that defines how DAP4 supports asynchronous responses, e.g., when a request will take the server time to fulfill.<br />
<br />
== Summary of Asynchronous Response ==<br />
<br />
== Overview: Asynchronous Service Behavior and Responses ==<br />
Asynchronous responses are responses that will take the server some time to build. When a client is told that a response 'is asynchronous,' it must know to come back at a later time to retrieve the response. The concept is a very simple one, and the existing network infrastructure is very good at supporting these kinds of interactions. A major factor in the success of the proposed solution will be the level of uniform support for the design. Secondly, as is often the case, the details will be more complex than the underlying concept. In particular, the request mechanism must be extended so that synchronous (regular) requests are not affected by the addition of asynchronous requests and, at the same time, clients do not inadvertently make asynchronous requests. another detail is that the (asynchronous) responses are ''ephemeral'' because they typically only persist for a period of time and then be purged.<br />
<br />
A typical 'workflow' for an asynchronous request is:<br />
# A client makes a data request that indicates that it will accept either an asynchronous or synchronous response. Optionally, the client can place a time constraint on the response, indicating that if the response will not be ready in a given period of time, it does not want the response.<br />
# The server returns an initial response (without delay) that indicates the request has indeed resulted in an asynchronous response and provides the client with a URL and time estimate. <br />
# The client reads the time estimate and waits...<br />
# The client dereferences the URL and gets the response.<br />
<br />
; Examples<br />
: A DAP4 server that is retrieving data content from a near-line tape storage subsystem might take several minutes to access a particular data holding. <br />
: A DAP4 server that is providing access to data held in an Amazon Web Services Glacier Vault will have to wait ~4 hours before it can retrieve a particular holding. <br />
In these circumstances the server may return the DAP4 Asynchronous Response.<br />
<br />
The remainder of this section will expand on this basic workflow using examples that focus on the HTTP protocol but that also allow for the use of other transport protocols.<br />
<br />
== Client willingness to accept asynchronous responses ==<br />
A client can indicate willingness to accept asynchronous responses in one of two ways:<br />
* By including the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header.<br />
* By adding the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword to the DAP constraint expression.<br />
<br />
If the client indicates that it must have access to the asynchronous response content within a certain time (utilizing either the [[#Accept DAP Asynchronous Response|X-DAP-Async-Accept]] HTTP header and/or the [[#DAP4_Constraint_Expression_extension_for_Async | async]] keyword in the constraint expression) and the response will not be available in that time frame, the server MUST reject the request and return an HTTP status of [[#412_Precondition_Failed | 412]] and the [[#DAP Asynchronous Request Rejected | DAP Asynchronous Request Rejected]] XML document.<br />
<br />
If both the ''X-DAP-Async-Accept'' HTTP header and the ''async'' keyword are used, the keyword takes precedence.<br />
<br />
Servers must reject requests that require an asynchronous response if the client has not indicated willingness to accept such a response. Rejection of such requests is indicated by all three of the following:<br />
# [[#400 DAP Asynchronous Response Required| HTTP status of 400]]<br />
# Inclusion of the [[#DAP Asynchronous Response Required|X-DAP-Async-Required]] HTTP response header<br />
# The response body must contain the [[#DAP_Asynchronous_Response_Required | DAP Asynchronous Response Required]] XML document. <br />
This safety check (requiring clients to explicitly indicate their willingness to accept asynchronous responses) is required because otherwise very simple clients might inadvertently make requests that will result in an asynchronous responses, and these kinds of responses are likely to use disproportionately (relative to synchronous responses) more server resources. We want to make DAP4 so that simple clients work well and don't encounter unexpected 'hiccups.'<br />
<br />
== Initial processing by the server ==<br />
When a request is accepted by the server and it will result in an asynchronous response, the server MUST the server MUST return a 202 (Accepted) HTTP<br />
status code and the [[#DAP Asynchronous Request Accepted | DAP Asynchronous Request Accepted ]] XML document. This document contains a URL to the pending result of the request.<br />
<br />
Of course, this discussion is about the mechanism that enables a client to make a request and the server to provide ''information about'' an asynchronous response to that request. It does not cover any of the nearly infinite ways a server might actually make the ''content'' of that response. It is likely that servers will write the responses to files and the URL returned to the client will be used to retrieve that file, but there's no requirement that servers do that. The only requirements on server are that:<br />
#The URL returned asserts, using the [[#DAP4_Constraint_Expression_extension_for_Async | constraint expression syntax for async]] that the client accepts async responses.<br />
# The URL returned can be dereferenced and that operation will return the response requested by the client.<br />
<br />
== Response retrieval by the client ==<br />
When a client requests an asynchronous result that is ready, the server MUST return a 200 (OK) HTTP status code and the resulting data response. If the client attempts to access the asynchronous result prior to it's availability, the server SHOULD return an HTTP response status of [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 (DAP Response Not Ready)]] along with the [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP Asynchronous Response Not Available]] XML document. If the server does not return the 409 response status then it MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
If the client attempts to access the asynchronous result after it is no longer available, the server SHOULD return an [[#410_Gone_-_DAP4_Response_No_Longer_Available | HTTP response status of 410 (Gone)]] along with the [[#DAP4_Asynchronous_Response_Gone| DAP4 Asynchronous Response Gone]] document. If the server does not return the 410 response status then the server MUST return a 404 (Not Found) response along with whatever document it deems fit as the response body.<br />
<br />
In each case above where the server SHOULD return a specific error code, but may return a 404 code instead, the intent is for servers to provide the most appropriate use of HTTP/1.1's error codes while also providing servers with an 'out' when that is hard for them to do. For example, knowing that a response, which is essentially ephemeral, is gone would, in theory, require to server to keep a record of every URL ever issued for an asynchronous response and that is not practical. At the same time, it is easy to see that a client would really like to know that the response has not yet been finished (i.e., it has not waited long enough) or that it is gone (i.e., it waited too long).<br />
<br />
== Detail: Client requests ==<br />
<br />
=== DAP4 Constraint Expression extension for Async ===<br />
By adding a keyword/value pair to the DAP4 query string we can allow a client to encode it's willingness to accept an asynchronous response, along with the a maximum amount of time the client can wait before it can access the response. <br />
<br />
; dap4.async<br />
: A value of zero indicates the client is willing to unconditionally accept an asynchronous response. A positive integer value will be interpreted as the number of seconds that the client will wait for access to the response. If the value is negative the serve MUST return an error. <br />
<br />
; Examples<br />
: Client is willing to unconditionally accept an asynchronous response<br />
:: <code>?dap4.async=0</code><br />
: Client is willing to wait for 60 seconds for access to the asynchronous response<br />
:: <code>?dap4.async=60</code><br />
<br />
=== X-DAP-Async-Accept ===<br />
<br />
A client may indicate willingness to accept asynchronous responses by including the ''X-DAP-Async-Accept'' HTTP header. Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
== Detail: Server responses ==<br />
<br />
Several 'experimental' HTTP headers are used by this design. They convey information either in the request (like the ''X-DAP-Async-Accept'' described above) or they encode information for a response. While only clients that intend to support asynchronous responses need to understand all of these, ''every'' client SHOULD understand the ''X-DAP-Async-Required'' header. Because we need to support clients like web browsers, knowledge of that header is not required, but DAP4-specific clients will provide the most information to users if they know to look for at least that response header.<br />
<br />
=== HTTP Response Headers ===<br />
==== X-DAP-Async-Required ====<br />
<br />
The ''X-DAP-Async-Required'' HTTP response header is included in the response if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[#400_DAP4_Asynchronous_Response_Required |400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
==== X-DAP-Async-Accepted ====<br />
<br />
The ''X-DAP-Async-Accepted'' HTTP response header is included in the response if the server has accepted an asynchronous request. Acceptance of the request should also be indicated by the [[#202_Accepted|202 Asynchronous Request Accepted]] HTTP response code.<br />
<br />
=== HTTP Response Codes ===<br />
<br />
HTTP provides a number of response codes beyond the simple 200 (OK), 404 (Not Found) and 500 (Internal Server Error). In this design we describe how those standard codes SHOULD be used by DAP4 servers. We don't enumerate all of the possible codes, instead opting for a description of those that most relevant.<br />
<br />
==== 202 Accepted ====<br />
<br />
A server indicates that a request has been accepted and will be handled asynchronously by returning a '202 Accepted' HTTP response code. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types|below]]. A server MUST return this response, and only do so, when a client has indicated a willingness to process an asynchronous response and the response will actually be returned using the asynchronous mechanism.<br />
<br />
==== 400 DAP4 Asynchronous Response Required ====<br />
<br />
The '400 DAP Asynchronous Response Required' HTTP response code is used to indicate that the DAP4 request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response.<br />
<br />
The response code text is used to indicate the reason for the rejection. However, since the '400' HTTP response code is not specific to asynchronous DAP (the standard text for the '400' code is "Bad Request"), the ''X-DAP-Async-Required'' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response|above]]).<br />
<br />
'''Note''' that a standard 400 HTTP response code is returned. In this way, a client that does not understand asynchronous DAP can fail gracefully. The response code text message has been changed to be more informative of the reason for the failure. For clients that are aware of asynchronous DAP, the "DAP-Async-Required" header is set to "true". The body of the response also returns some information the client can use to decide on how it will continue.<br />
<br />
==== 409 Conflict - DAP4 Response Not Ready ====<br />
<br />
The '409 Conflict' HTTP response code MAY be returned by a server to indicate that the DA4P request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. If a server utilizes the '409 Conflict' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document in the response body.<br />
<br />
==== 410 Gone - DAP4 Response No Longer Available ====<br />
<br />
The '410 Gone' HTTP response code MAY be used by a server to indicate that the result of an asynchronous request is no longer available. If a server utilizes the '410 Gone' HTTP response code it must also return a [[#DAP4_Asynchronous_Response_Gone | DAP4 Asynchronous Response Gone]] document in the response body.<br />
<br />
==== 412 Precondition Failed====<br />
<br />
The '412 Precondition Failed' HTTP response code is used to indicate that the DAP request has been rejected because it did not meet the '''X-DAP-Async-Accept''' condition (see [[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion|above]]) that was specified in the request.<br />
<br />
==== 500 Internal Error====<br />
<br />
The '500 Internal Error' HTTP response code is used to indicate that the DAP request has caused an error on the server. The request body and other headers must be compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
=== Asynchronous Response Documents ===<br />
<br />
The uses of these documents are:<br />
* to inform clients that a request will result in an asynchronous response;<br />
* to provide clients with the status of an an accepted asynchronous request; and<br />
* to inform clients that a request for and asynchronous response has been rejected.<br />
<br />
These response documents are the payloads to various responses, including errors. By using the HTTP 400-series error response codes, the design ensures that generic web clients will understand that their request was in error (even if they don't really understand why). The text provided with the response code will be sufficient that person could understand the gist of the problem, if not more. The response documents described here, along with the ''X-DAP'' describe above, are a way of providing additional information to a savvy client so that it can take full advantage of the synchronous response system.<br />
<br />
These documents are XML that follows the DAP Asynchronous XML schema and are declared in the namespace '''<nowiki>http://opendap.org/ns/dap/asynchronous</nowiki>'''.<br />
<br />
==== DAP4 Asynchronous Response Required ====<br />
<br />
This document informs clients that a request will result in an asynchronous response, and that the client has not yet indicated it's willingness to accept an asynchronous response. It might seem superfluous to include a document that clearly only a client knowledgable about the asynchronous response features could parse, but many such clients may not, as a matter of course, indicate they will accept these responses. For example, a user-configurable parameter might be turn off support for the feature. The ''expectedDelay'' and ''responseLifetime'' elements convey information about conditions the clients can expect if it submits an asynchronous request for the response. As noted below, these are estimates made by the server since a number of things that the server cannot predict can affect them in the interleaving time between the client's requests. Additionally, a server MAY return values of zero for either of the values, indicating that it cannot make an accurate estimate.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response MUST be associated with the 400 HTTP response code and the ''X-DAP-Async-Required'' response header.<br />
<br />
==== DAP4 Asynchronous Request Accepted ====<br />
<br />
This response informs clients that a request resulting in an asynchronous response has been accepted, along with operational information about retrieving the asynchronous response result. Note that the ''expectedDelay'' and ''responseLifetime'' elements are an estimate by the server. A server SHOULD ensure that the response will remain available for the time period given by ''expectedDelay'' and ''responseLifetime''. We say ''SHOULD'' and not ''MUST'' because we cannot predict all possible operational situations where these kinds of responses might be used. For example, a server might be providing access for several types of users who might have different access priorities, especially to limited resources like those typically involved with asynchronous access, and thus some responses might be further delayed, or removed early, to enable processing of requests from users with higher priority. It should be kept in mind, however, that the usefulness of the asynchronous responses will depend, in part, on servers providing a facility on which clients can depend.<br />
<br />
While the ''expectedDelay'' and ''responseLifetime'' elements are required, a server MAY set their ''seconds'' attribute to ''0'' to indicate that it cannot provide a reliable value. In this case, clients SHOULD poll every 300 seconds and servers SHOULD expect this behavior. This is the default TCP user timeout period (see http://tools.ietf.org/html/rfc5482).<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
This response document MUST be associated with the 202 HTTP status code and the ''X-DAP-Async-Accepted'' response header.<br />
<br />
==== DAP4 Asynchronous Response Not (Yet) Available ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is not available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="pending"/><br />
</source><br />
This response document MUST be associated with the [[#409_Conflict_-_DAP4_Response_Not_Ready | 409 HTTP response code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 409, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Response Gone ====<br />
<br />
This document informs clients that a while a previous request for an asynchronous response has been accepted, the result is ''no longer'' available.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="gone"/><br />
</source><br />
This response document MUST be associated with the [[#410_Gone_-_DAP4_Response_No_Longer_Available| 410 HTTP status code]]. <br />
<br />
Servers SHOULD return this response document and it's associated HTTP status of 410, but servers MAY return any document in the response body along with either a a 404 (Not Found) or a 400 (Bad Request) HTTP status.<br />
<br />
==== DAP4 Asynchronous Request Rejected ====<br />
<br />
This document informs clients that a request for an asynchronous response has been rejected, even though the client said it is willing to process an asynchronous response. There are at least as many reasons a server might reject the request for an asynchronous response as there are systems that might return such responses. However, this design provides suggested response codes for cases that seem likely so that clients can make educated decisions about the reason for the rejection. The reason codes supported are:<br />
;time: The client indicated that it was only willing to wait ''X'' seconds and the server thought it would take more time to build the result.<br />
;unavailable: A needed resource is not available. This might indicate that hardware, like a robot tape system, cannot be currently accessed.<br />
;privileges: The client is not allowed to make the request. <br />
;other: Self evident...<br />
In addition to the reason codes, this response will contain a text description of the reason for rejection.<br />
<br />
Servers SHOULD make every effort to use the correct reason codes and provide cogent descriptions.<br />
<br />
<source lang="xml"><br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
This response document MUST associated with the 412 HTTP status code. <br />
<br />
Servers SHOULD return this response document along with an HTTP status of 412, but servers MAY return any document in the response body along with an HTTP status of 404 (Not Found) or of 400 (Bad Request) in its place.<br />
<br />
==== DAP4 Error ====<br />
<br />
If the server encounters an error it must MUST (MAY?) return an HTTP status of 500 (Internal Error) along with a request body and other headers compliant with the [[DAP4_Web_Services_v3#DAP4_Error_Response | DAP4 Error Response]] and [[DAP4_Web_Services_v3#Status_Codes | Status Codes]] sections of the [[DAP4_Web_Services_v3 | web services specification]]. The request should not be repeated.<br />
<br />
== Examples ==<br />
<br />
=== Constrained Data Request-Response using GET ===<br />
<br />
; Simple Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
If the server decides it needs to handle this request in an asynchronous manner, it will refuse the request because it did not say it would accept an asynchronous response.<br />
<br />
; Response:<br />
<source lang="xml"><br />
400 DAP Asynchronous Response Required<br />
X-DAP-Async-Required: true<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="required"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 0<br />
<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=0&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
202 Accepted<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="accepted"><br />
<expectedDelay seconds="600" /><br />
<responseLifetime seconds="3600"/><br />
<link href="http://server.org/async/path/result" /><br />
</AsynchronousResponse><br />
</source><br />
<br />
'''NB''': This example originally included an ''Accept'' header with the value of ''multipart/mixed''. However, that is not a good example. The HTTP/1.1 specification says that when a specific media type is indicated as the only one acceptable, a server must return a 406 response code if it cannot return that media type. The meaning of ''Accept: */*'' is the same as not including the header, so I have removed the header from these examples. We need to be heads up in the ways that we suggest that header should be used by clients<br />
<br />
=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===<br />
<br />
Request:<br />
<pre><br />
GET /dap/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
X-DAP-Async-Accept: 60<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /dap/path/data.nc.dap?dap4.async=60&dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Response:<br />
<source lang="xml"><br />
412 Precondition Failed<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="rejected"><br />
<reason code="time"/><br />
<description>Acceptable access delay was less than estimated delay.</description><br />
</AsynchronousResponse><br />
</source><br />
<br />
=== Premature Request For Asynchronous Result ===<br />
<br />
Request:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
Alternately, this request would produce the same result using only the URL:<br />
<pre><br />
GET /async/path/data.nc?dap4.ce=x,y,temp HTTP/1.1<br />
Host: server.org<br />
</pre><br />
<br />
<br />
Response:<br />
<source lang="xml"><br />
409 Conflict<br />
Content-Type: text/xml;charset=UTF-8<br />
<br />
<AsynchronousResponse status="pending"/><br />
</source><br />
<br />
== Resource Role ==<br />
<br />
DAP4 Asynchronous Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/async</nowiki></code></font>'''<br />
<br />
== Normative Encoding of the Asynchronous Response ==<br />
<br />
The normative XML representation for the Asynchronous Response is defined in Appendix x "Normative XML Encoding of the Asynchronous Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.dap4.async.xml'''</code></font></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4:_Overview&diff=10530DAP4: Overview2014-04-21T23:30:07Z<p>EthanDavis: </p>
<hr />
<div><br />
Following two decades of stability and increasing use, DAP2 is being superseded by DAP4, the first substantive revision in the history of the Data Access Protocol (DAP), an open-source endeavor led by OPeNDAP, Inc. The primary and continuing purpose of DAP is to realize ''remote, selective, data-retrieval as a widely-accepted and well-crafted Web service''. This document outlines the fundamental concepts of DAP4, and (targeting those who have already programmed DAP-compatible clients and servers) it highlights how DAP4 differs from DAP2.<br />
<strike>In the following, DAP refers to DAP4 unless indicated otherwise.</strike><br />
<!-- This last sentence is rendered unnecessary and wrong by the first sentence where DAP2, DAP4, and DAP are define (somewhat implicitly). - Ethan<br />
--><br />
<br />
= Data Retrieval as a Web Service =<br />
<br />
The premise underlying DAP4 remains, as in DAP2, that values from data sources—or, notably, from proper subsets—along with pertinent metadata may be acquired remotely and effectively through an appropriately defined Web service, operated near the source data. To a surprising degree, DAP services shield users from idiosyncrasies in source-data formats and storage, so DAP functions as middleware with a further advantage: source-data and users may reside anyplace that has Internet connectivity. OPeNDAP's commitment to open source has fostered several DAP-compatible servers and an even larger number of DAP-compatible client environments, several of which (i.e., servers, clients and client-server libraries) are available at no cost.<br />
<br />
DAP is designed for selectively retrieving (but not for storing) data organized as variables or groups of variables. It is well suited to cases where client computers retrieve data stored on remote computers (i.e., servers) networked to the client, especially where data sources are huge (comprising large arrays, e.g.) but clients typically need only small subsets of them. The protocol is fundamentally stateless (some might say “RESTful”), and it governs how clients pose requests and how servers issue corresponding responses.<br />
<br />
DAP’s effectiveness is keyed on the underlying data model, which embraces a rich variety of data types (including tabular and array structures). Based on this model, DAP spells out the (type-specific) retrieval operations that clients may request. The flexibility and domain-neutrality of the DAP data model (which has changed modestly between DAP2 and DAP4) make it effective—as middleware, per the above—across a broad range of data types and disciplinary domains. Stated another way, many kinds of data sources and schemas can be mapped onto the DAP model for retrieval and use by client computers and software.<br />
<br />
= Understanding the DAP Data Model =<br />
<br />
== A Brief Data-Model Summary ==<br />
<br />
Unlike FTP and other protocols enabling clients to access whole files or granules, DAP offers sub-granular retrievals, and this requires exposing the detailed structure of each granule (called a “dataset” in DAP). To this end, the structure of every DAP-accessible dataset is manifest in a machine-readable document called the DMR. DMRs are declaration statements that adhere formally to the DAP Data Model, which is sufficiently general to make retrievable a variety of data granules and data types whose semantics vary widely among the (potential) sources.<br />
<br />
The DAP data model is built around a notion of “variables” that fall into three classes—atoms, structures and sequences—and may be organized as multidimensional arrays. As reflected in its DMR, all of a dataset’s variables are named, and they may optionally be grouped (in a hierarchy) to add meaning and allow complex name-driven retrievals by clients. DAP variables are (strongly) typed and optionally may have “attributes” and “dimensions”, the former to clarify meaning and the latter to indicate a variable’s array shape (where relevant). Attributes resemble variables except that the former may be assigned to the latter, but not vice versa.<br />
<br />
Much of DAP’s power arises from its typing structure. The value(s) of an atomic variable (whether or not dimensioned as an array) are all of the same atomic type, indicated in the DMR to be integer, floating point, character, string, etc. Structure variables are combinations of atom variables joined for semantic reasons, such as to represent complex numbers, vector-valued parameters, or other relationships among the values of a dataset.<br />
<br />
To address a difficult abstraction challenge—retrievals from both array-oriented and database-oriented sources—DAP allows DMRs to declare variables of type “Sequence”. A sequence is like a relation, i.e., a table whose rows are “instances” or “records” and whose columns contain the values of “fields”. In DAP, the content of a sequence may comprise an arbitrary number of instances (i.e., records) whose “fields” are values from other DAP variables. <br />
<br />
For example, a sequence named “BirdTracking” might contain variables named “BirdID”, “BandingEvent”, and “ObservedPosition”, and the contents of BirdTracking would be instances that contain values of the specified variables (fields). DAP allows arbitrary nesting of sequences and structures, so in this example BandingEvent could be a structure (containing date and location info for the bird’s banding) and ObservedPosition could be a sequence (containing equivalent date and location info) whose instances represent subsequent bird observations.<br />
<br />
Hypothetically, this is akin to making BirdTracking a structure with a single dimension (though DAP does not allow arrays of indefinite length). However, selective retrieval from an array would require knowing the indices of desired instances, whereas a BirdTracking sequence allows filtering-style retrievals that select instances on the basis of their values.<br />
<br />
== A Rough Glossary of Data-Model Entities ==<br />
<br />
Much about DAP may be discerned from a dictionary or glossary-like list of the key entities in its data model. Such a list follows, sequenced for ease of understanding (rather than alphabetically). These descriptions are not definitive, as the formal specification documents take precedence over anything stated here.<br />
<br />
'''Data Source''' - Though formally outside the DAP Data Model, the term Data Source generally refers to all the datasets (see below) that may be retrieved via DAP from a single server, identified by its domain name. Servers sometimes offer (catalogs and/or inventories of) collections and sub-collections, but the DAP Data Model focuses on granular and sub-granular retrievals.<br />
<br />
'''Dataset''' - Sometimes called a “granule” in catalog/inventory parlance, a DAP Dataset is represented by a unique (unadorned) URL, and is the highest-level entity (metadata as well as content) described by the DAP Data Model. Clients invoke retrieval operations by adorning the Dataset URL with suffixes and query strings interpreted by the server.<br />
<br />
'''Declarations and the DMR''' - For a specific Dataset, all aspects of the DAP Data Model (name assignments, structural definitions, etc) are governed by a formal declarations document. Created as part of making a Dataset DAP-retrievable, this document is dubbed the DMR (roughly: Dataset Metadata Response), and clients may retrieve DMRs alongside or independently of Dataset contents.<br />
<br />
'''Name''' - Most entities in the DAP Data Model may or must be named. With some constraints on the use of special characters (such as “.”), a Name can be any character string. To avoid conflicts, DAP has scoping rules. For example, a Variable and a Dimension may have the same Name without ambiguity, but two Variables can have the same Name only if they are declared in different Groups or structures.<br />
<br />
'''Variable''' - The building blocks for the DAP Data Model are Variables, which are strictly typed. Three classes of them (atoms, structures and sequences) are described separately below, but in actuality these are best distinguished by inspecting their Type declarations. Each Variable must be assigned a Type and a Name, and it may optionally have a number of Dimensions and Attributes, elaborated below.<br />
<br />
'''Type''' - Underpinning DAP’s “container” Types (Structure and Sequence, implied above) are “atomic” Types akin to those of computer languages: bytes, integers, floating-point values, strings, and URLs, plus an enum type (permitting specified character strings, such as days of the week, to be treated as variable values) and an opaque type (permitting arbitrary blobs of bits). More detailed Type descriptions are provided in Volume I of the DAP specification.<br />
<br />
'''(Atom) Variable''' - A Variable whose Type is atomic (see above) comprises a single value or an array of values, and all its values are of the designated Type. A Variable is an array only if its declaration includes Dimensions, which determine the array’s shape and its element-ordering (see below).<br />
<br />
'''(Structure) Variable''' - A Variable of Type “Structure” is a container for other variables, often implying relationships among them. For example, a structure Variable named “Velocity” might contain a pair of atom Variables (or fields) named “x” and “y,” representing components of a velocity vector. These components would be retrieved via their “qualified” Names, “Velocity.x” and “Velocity.y”.<br />
<br />
''Notes on Structures:''<br />
<ul> <br />
<li>Structures may contain variables of any type, including other structures.</li><br />
<li>A contained variable can be used in the context of several containers, but these contexts create separate, independent instances.</li><br />
<li>If the semantics of a variable are altered by its context, it should be separately declared in each relevant context. For example, declarations for the atoms “Velocity.x” and “Displacement.x” should be distinct and separate (falling within “Velocity” and “Displacement” declarations respectively) despite reuse of the name “x”.</li><br />
<li>Though a dimensioned structure resembles a structure containing dimensioned variables (with the same shapes), these are not equivalent, and the means for referencing them differ. For example, array element i,j would be referenced as:<br />
<ul><br />
<li>Velocity[i,j].x if two dimensions are assigned to the Velocity structure.</li><br />
<li>Velocity.x[i,j] if two dimensions are assigned to its x-component variable.</li><br />
</ul><br />
</li><br />
</ul><br />
<br />
'''(Sequence) Variable''' - A Variable of Type “Sequence” is a container holding multiple (unordered) instances of other DAP Variables. For example, a sequence Variable named “TracerParticle” might contain a pair of structures named “Velocity” and “Displacement”, each declared—as in an earlier example—to have x and y components. The instances of TracerParticle would be like a set of tabular records whose four fields, Displacement.x, Displacement.y, Velocity.x, and Velocity.y are retrieved via filter-style (rather than indexed) retrievals, as discussed in a later section on Constraints.<br />
<br />
''Notes on Sequences:''<br />
<ul><br />
<li>Sequences may contain variables of any type, including other sequences.</li><br />
<li>Though a sequence is similar in some respects to a structure with a single (indexing) dimension, the differences are significant. For example, if a DAP server offers retrieval of records from a relational data base:</li><br />
<li>The most useful client retrievals may entail filtering based on the values in the fields, and this yields indexing gaps. In other words, indexing may have little or no utility.</li><br />
<li>The number of records may be hidden or dynamic, so a dimension length cannot be calculated, and the order in which records are returned may be volatile.</li><br />
</ul><br />
<br />
'''Group''' - The DAP Data Model has a hierarchical mechanism for grouping Variables and carving out independent namespaces. Groups may be nested, and all but one must have Names, the exception being the root of the hierarchy, where the Dataset itself is a Group (needing no name). Retrieving a Variable whose declaration falls within a Named Group requires use of its fully qualified name (FQN), such as GroupA.Group2.Velocity. Any Group (including the Dataset) may be assigned Attributes but not Dimensions.<br />
<br />
'''Attribute''' - Otherwise nearly indistinguishable from a Variable, an Attribute must always be assigned to a specific Variable or Group. The purpose of Attributes is to provide context or add meaning to the assigned entities, whereas the purpose of Variables is to convey primary content. Retrieving an Attribute always requires prepending the name of the Variable or Group to which it is assigned, which implies that Attribute Names (such as “Units”) enjoy unlimited reusability.<br />
<br />
'''Dimension''' - A Dimension must have a size and may have a Name. A Variable of any type may optionally be assigned a number of Dimensions, in which case its (compound) values are organized and retrieved as an indexible array of rank n, where n is the number of assigned Dimensions.<br />
<br />
''Notes on Dimensions:''<br />
<ul><br />
<li>Named Dimensions resemble named constants. Indeed, assigning a named dimension to multiple variables (within the scope of a single group) has the same effect on each, giving definition to that variable’s array shape and array-element ordering.</li><br />
<li>Unlike attributes, dimensions often are declared outside the variables to which they are assigned. Groups may not accept dimension assignments, but groups limit the scope of the dimension names and sizes declared within them.</li><br />
<li>Dimensions names may be reused, with differing sizes across multiple groups.</li><br />
<li>The order of the dimension assignments in a variable declaration is significant, as this determines the variable’s array-element ordering as well as its shape.</li><br />
<li>Retrieving a dimension may require prepending the name of the group in which it was declared but never the name of a variable to which it has been assigned.</li><br />
<li>A Dimension’s size must be a positive integer less than 2^61.</li><br />
</ul><br />
<br />
== Higher-Level DAP Objects and Extensions ==<br />
<br />
Shared Dimensions that serve to indicate relations between different arrays which can be used to build/represent Coverages...<br />
<br />
Note: Though adoption to-date has been most pronounced in Earth sciences, DAP’s data types and structures (with the possible exception of coverages, discussed in this section) are not at all specific to these disciplines, so we think DAP is positioned for effective use in many domains, scientific and otherwise.<br />
<br />
= Client Use of a DAP Data Source =<br />
<br />
== High-Level Info about DAP Datasets: the DMR ==<br />
<br />
A client's first step in selectively retrieving a data source often is to discern the character (i.e., its schema) by requesting what DAP calls the DMR (the data-source metadata response). A DMR provides a complete characterization of the associated data source sans content, spelling out its groups, variables, types, dimensions, and attributes as discussed in the preceding two subsections. For ease of use in client software, the DMR adheres to a formal syntax and most often is delivered as an XML document, though other forms are anticipated as DAP4 ''extensions''.<br />
<br />
Though it is common to retrieve its DMR prior to requesting content from a data source, this is not the only option. Indeed, a "Data Request" under DAP returns both the DMR and the content (i.e., the ''values'' of variables) for the designated data source, because the former is critical for interpreting the latter.<br />
<br />
== Retrieving Content from DAP Datasets: Posing DAP Requests ==<br />
<br />
Under DAP, the requests clients make of servers, and the resulting server responses, are all governed by the protocol specification. As stated previously, the formal specification takes precedent over anything stated here.<br />
<br />
For each data source, a number of responses may elicited by a client, determined by adding a suffix and/or a query string to the basic URL for the desired data source. Passing the server a completely ''unadorned'' URL yields a Dataset Services Response (DSR). This XML document describes the various DAP services available for that source, and these always include provision of a DMR and provision of ''content'' from the source. Unlike the DMR, which is always textual, content (delivered in response to a Data Request, as discussed above) may be conveyed in textual ''or'' binary form, the latter minimizing data-transfer volumes, of course.<br />
<br />
If the URL for a Data Request includes a query string, the server parses this string to determine what data processing the server should perform before constructing its Data Response. Though other classes of pre-retrieval processing are anticipated to be defined via DAP extensions, two forms are mandated by DAP4 for all servers, Index Subsetting and Field Subsetting, and a third form, Filtering, is defined in the core DAP specification, though its implementation by servers is optional.<br />
<br />
'''Index Subsetting''' - Choosing parts of an array based on the indexes of that array's dimensions. This operation always returns an array of the same rank as the original, although the size of the return array will (likely) be smaller. Index subsetting uses the bracket syntax described later.<br />
<br />
'''Field Subsetting''' - Choosing specific variables or fields from the dataset. A dataset in DAP4 is made up of a number of variables and those may be Structures or Sequences that contain fields (and, in effect, the Dataset is itself a Structure and all of its variables are fields - the distinction is more convenience than formal). Field subsetting using the brace syntax described later. One or more fields can be specified using a semicolon (;) as the separator.<br />
<br />
'''Filtering''' - A filter is a predicate that can be used to choose data elements based on their values. the vertical bar (|) is used as a prefix operator for the filter predicate. Filters can be applied to elements of an Array or fields of a Sequence. A filter predicate consists of one or more filter subexpressions. One or more subexpressions can be specified, using a comma (,) as the separator.<br />
<br />
Other services listed in the DSR might (at the server's option) include the DAP Asynchronous Response. Where implemented (such as for near-line data sources), this response is sent to the client when the requested resource (DMR, Data Response, etc.) is not immediately available. If, in turn, the client makes a "retrieve it" request, the server will respond with a second Asynchronous Response informing the client about when and where the requested resource may be retrieved.<br />
<br />
In addition to the most common data objects, a DAP server ''may'' provide additional "services," such as HTML-formatted representations of a data source's structure and content. Such additional services are discussed in Volume 2 of the specification.<br />
<br />
= The Formal DAP Specification =<br />
<br />
The DAP4 specification spans two volumes: one describes the Data Model and DAP’s Request/Response objects; the other volume describes how DAP clients and servers communicate via HTTP and the modern Web. New volumes about DAP Extensions will be added as they emerge.<br />
<br />
Partitioning the specification into two primary documents reflects the independence of DAP’s data-retrieval functionality from the underlying network transfer protocol. Indeed, DAP could be used with other transports. However, utilizing HTTP eases the building of DAP servers because they can take full advantage of widely used Web-server frameworks such as Apache. Use of Extensions documents will enable evolution of the protocol without the expense and complexity of another major protocol-development project. Anticipated extensions include a JSON encoding for DAP data/metadata and the provision of server functions (beyond DAP’s core subsetting and filtering operations).<br />
<br />
'''The specification is available at these links:'''<br />
<br />
* [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
* [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
* Extensions:<br />
** [[DAP4 Extension: CSV Data Encoding and Response]]<br />
** [[DAP4 Extension: Asynchronous Response]]<br />
<br />
= How DAP4 Differs from DAP2 =<br />
<br />
Though the protocol, per se, is maintained primarily by OPeNDAP, many others have engaged in DAP2 realization. One implementation—by Unidata, in the University Corp. for Atmospheric Research—includes the popular THREDDS Data Server (TDS). A key motivation for DAP4, developed jointly by OPeNDAP and Unidata, was to reduce differences that have arisen, and impede interoperability, among DAP2 realizations. Our hope is that a modernized, clearer and more comprehensive specification will facilitate building clients and servers with greater interoperability, making such ventures more rewarding and less risky.<br />
<br />
This section covers changes to the data model, response formats, and serialization, giving developers a roadmap to migration from DAP2 to DAP4. E.g., the “Grid” type now supports a notion of discrete functions similar to an OGC/ISO Discrete Coverage and to the Scientific Data Type found in Unidata’s Common Data Model (CDM). Also from this section, users may learn of functionalities to seek in clients. E.g., DAP4 servers return checksums with each data response, but clients may utilize these in varying degrees. <br />
<br />
DAP4 is largely an extension of DAP2 concepts, including ideas that emerged as DAP gained prominence across the Earth sciences. Therefore DAP2-compatible software, in clients or servers, should be easy to adapt to DAP4, and this has been affirmed in the OPeNDAP-Unidata realization and testing work. Furthermore, DAP4 exhibits backward compatibility sufficient to enable gradual transitioning. Substantive changes include support for Groups, yielding greater compatibility with HDF and NetCDF4.<br />
<br />
== Data-Model Changes ==<br />
<br />
'''Summary''': DAP4 now supports groups, a generalized form of a grid datatype and a few new atomic types.<br />
<br />
The DAP4 data model is fundamentally similar to that for DAP2. New atomic types include: enumeration, 64-bit integer, and opaque, and the container types now include groups. Groups provide a way to organize collections of variables and dimensions and to encode these organizational relationships when they are present in the underlying source data.<br />
<br />
Dimensions may now be named, and the presence of shared dimensions (i.e., several variables employ a dimension with a given name) along with explicitly name 'maps' serves to indicate relationships among arrays that can, in turn, be used to build/represent a more general form of the DAP2 Grid datatype that resembles the OGC/ISO "discrete coverage" datatype. These 'discrete coverages' subsume the role of DAP2 Grids, so the latter have been removed from DAP4.<br />
<br />
'''Migrating from DAP2 to DAP4'''<br />
<br />
For servers: A DAP2 DDS/DAS (or DDX) is very close to a DAP4 DMR (indeed, our C++ library contains a way to build a DMR from a DDS). The set of datatypes supported by DAP4 is almost a proper superset of those in DAP2, the exception being that DAP2's Grid type has been removed. To represent a DAP2 Grid in DAP4, the components of the DAP2 Grid are retained and the appropriate Shared Dimension and Map elements are added to the dataset/group and array. Since the DAP4 'discrete coverage' type subsumes the DAP2 Grid, it will always be possible to translate a DAP2 Grid into DAP4<br />
<br />
For clients: Some of the new data types are more challenging to implement than the types included with DAP2. Of particular note are Enumerations and the expanded grid (aka 'discrete coverage') types.<br />
<br />
== Changed Responses ==<br />
'''Summary or the main changes between DAP2 and DAP4 Responses''':<br />
* DAP4 includes only one dataset ''metadata'' response, not two;<br />
* Several Sequences may be individually constrained in one access; <br />
* Predictable behavior for 'bare' URLs; and<br />
* Asynchronous responses<br />
<br />
In DAP4 there is a single XML document that encodes the metadata for a data source. This response is conceptually similar to, and in some ways identical too, the ''DDX'' response that is supported by many DAP2 servers, so it's organization will be familiar to many people already. As with DAP2, there is one data response that can be modified (''constrained'') using a expression to limit the information it includes. The basic concepts of slicing an array are unchanged in DAP4. We've taken care to allow servers to extend the information passed into the data retrieval web service, a topic that is covered in a bit more detail below under ''web services.'' We have replaced the ''selection'' part of the DAP2 constraint expression with a ''filter'' sub-expression that is applied to specific variables. This enables two or more Sequences to have their own filtering operations (before that was not possible). Our expanded constraint language also provides a way to subset coverages, and a proposed extension to the filtering sub-expression provides a way to subset arrays/coverages by value.<br />
<br />
We wanted DAP4 to fully embrace REST. DAP2, even though it predates the term, including many, but not all, of the REST architecture's features. One change from DAP2 was to explicitly define what happens when a client dereferences a 'bare URL' (one without an extension used to ask for a specific DAP4 response). When a DAP4 sever is asked to return information at a bare URL, the result is a Dataset Services Response (DSR) which contains links to all of the other responses for that dataset. In addition, the DSR may contain other information such as server operations that can be used with the dataset. The DSR is an XML document but can contain a stylesheet that transforms it to HTML for a web browser. <br />
<br />
DAP4 servers can also support asynchronous access to data, which enables access to data from near-line devices and can be used for some server processing operations (e.g., operations that take a long time to perform). Asynchronous responses are responses that contain a URL that can be used to retrieve the actual data at some time in the future. The protocol has been designed to reduce the chance that a client will mistakenly make a large number of asynchronous requests since this could present an undue burden on some kinds of near-line devices.<br />
<br />
'''Migrating from DAP2 to DAP4'''<br />
* If your server or client already reads DAP2 DDX responses (which were never part of the official protocol but are widely used) then adapting to the DMR will be very easy since they are very close in structure.<br />
* Support for the new constraints may take a bit more work since now the Constraint Expression and Server Functions have been separated.<br />
* Clients will benefit from asynchronous response support, but this is a new behavior and may take some serious thought, particularly for clients that relied on the simpler semantics borrowed from file system accesses.<br />
<br />
== Response-Encoding Changes ==<br />
'''Summary''':<br />
* Checksums for data values;<br />
* Reliable delivery of error messages to clients;<br />
* Encode data using the server's native word order.<br />
<br />
We have added three changes to the encoding of returned data values. All top-level variables in a data response now include a CRC32 checksum of their values. This enables people to see if a request is returning the same data values as it did previously. The checksum values are encoded in Attributes bound to the returned variables. We have added an encoding scheme for data values that preserves compactness yet allows clients to easily detect when a server has encountered an error while sending a response. Similarly, we have adopted a ''Reader Make Right'' encoding scheme instead of the ''network byte order'' scheme used by DAP2. The latter has become more and more important as the predominance of little-endian processors has increased.<br />
<br />
'''Migrating from DAP2 to DAP4'''<br />
<br />
In many ways the encoding scheme is simpler for servers because the data response uses the server's native byte order. Clients must detect the byte order and twiddle bytes as needed. However, the server must correctly implement the chunking protocol used by the data response and must correctly computer CRC32 checksums for each of the top level variables.<br />
<br />
== Changes in the Use of HTTP ==<br />
<br />
'''Summary''': DAP4 is closer than DAP2 to the REST (Representational State Transfer) architecture, and it uses HATEOS (Hypermedia As The Engine Of Application State), making all of the server's responses explicit via links in a document.<br />
<br />
While DAP2 interwove the DAP and HTTP, using, for example, some of the HTTP headers as the only source of information that was critical to the DAP itself, DAP4 does not. Instead, DAP4 is completely isolated from HTTP, enabling it to work with other protocols without change. However, in as much as HTTP is a ubiquitous network transport protocol, the DAP4 specification includes a volume devoted solely to how a server should implement DAP4 web services using HTTP. <br />
<br />
The REST interface for the protocol is described in Volume 2, ''Web Services,'' of the specification. DAP4 requires that a server implement at least three responses for each dataset: The DSR; DMR; and Data response. The DSR is a XML document that provides a ''capabilities'' response for the dataset. This document provides links to all of the other responses available for the dataset, along with other information. The DSR provides information about alternative encodings for the different responses in addition to enumerating the basic responses themselves. The DSR may also list server functions that may be used with/on the dataset. <br />
<br />
DAP4 servers are encouraged to support HTTP content negotiation, providing the standard DSR, DMR and Data responses in a variety of forms.<br />
<br />
'''Migrating from DAP2 to DAP4'''<br />
<br />
The web service for DAP4 will likely need to be written from scratch, but the good news is that those are easy to write. For clients, the behavioral differences between DAP2 and DAP4 servers are small, with two exceptions. Since DAP4 optionally supports asynchronous responses, clients should be modified to access data available only using this new feature. DAP4 also supports content negotiation and that means a larger number of ways to get the different responses (even though each protocol has three basic responses).<br />
<br />
= Acknowledgments = <br />
<br />
DAP4 is the result of a joint, multiyear development effort by OPeNDAP and Unidata, funded by a generous grant from NOAA and guided by an advisory committee comprising Mike Folk (THG), Jim Frew (UCSB), Steve Hankin (NOAA), Eric Kihn (NOAA), Chris Lynnes (NASA) and Rich Signell (USGS).<br />
<br />
<br />
<br />
<!--<br />
= Old Material, probably to be Discarded =<br />
<br />
The DAP Data Model<br />
<br />
A DAP server typically makes accessible a ''collection'' of data sources, each identified by a unique (unadorned) URL. As discussed below, clients pose requests by modifying this URL with DAP-specific suffixes and query strings. The following subsections only summarize the formal specification, which takes precedent over anything stated here.<br />
<br />
Elements of a DAP Data Source<br />
<br />
A DAP data source is fundamentally a collection of ''typed'' variables that have names, dimensions, attributes, and values. A variable's attributes and dimensions often are named as well. The ''types'' of variables in DAP are numerous, as outlined in the ensuing subsection. Furthermore, a variable having several dimensions is a natural and intuitive way to represent multidimensional arrays, and the DAP repertoire of client requests (see the subsection below on that topic) includes methods to retrieve ''subarrays'' per user specifications.<br />
<br />
Attributes are much like variables except they are intended to facilitate ''interpretation'' of the entities to which they are assigned. In contrast, variables contain the ''primary'' content of a data source. The scope of an attribute is limited by the entity to which it is assigned (i.e., a variable, a group, or an entire data source)). Thus, for example, variables T and V attributes with the same name (say "Units") but these attributes can have distinct ''values'', such as "K" when applied to T and "m/s" when applied to V. In contrast, dimensions are essentially named constants, so their (integer) values are completely independent of the variables with which they are associated.<br />
<br />
Variables and their attributes may be collected into ''named groups'' (which can be nested to yield hierarchies), and variable names may be reused in multiple groups without generating conflicts. For example, a variable named T appearing in a group named G1 is understood to be distinct from and formally unrelated to a variable named T appearing in a second group named G2. Dimensions may ''not'' be assigned to groups, as their scope is always global, as indicated above. The numbers of groups, variables, attributes and dimensions in a data source is unlimited.<br />
<br />
[?insert a table or tables showing how the above elements (i.e., groups, variables, types, dimensions, shapes relate to one another?]<br />
<br />
Atomic Types, Container Types and Enumeration Types<br />
<br />
The specified type of any DAP variable, whether or not it is an array, must be an atomic type, a container type, or an enumerated type as described in the following paragraphs. <br />
<br />
'''Atomic types''' - As with many programming languages the DAP atomic types include bytes, Integers (including 64-bit integers), floating-point values, and strings. DAP additionally includes the types URL and opaque, the latter to allow otherwise unspecified blobs of information.<br />
<br />
'''Container types''' - structures, sequences, groups...<br />
<br />
'''Enumeration types''' - <br />
--></div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10529OPULS Development2014-04-21T23:25:11Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
<br />
This section is deprecated in favor of the top-level [[DAP4 Specification |DAP4 Specification page]].<br />
<br />
<!-- DO NOT EDIT this page without editing the main DAP4 Specification page.<br />
(But this page doesn't need to match the main page wrt intro/overview paragraphs.)<br />
--><br />
<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: CSV Data Encoding and Response]]<br />
#* [[DAP4 Extension: NetCDF Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Specification&diff=10528DAP4 Specification2014-04-21T23:21:33Z<p>EthanDavis: Top-level DAP4 Specification page</p>
<hr />
<div>The DAP4 Specification has two main volumes and a number of optional extensions:<br />
<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: CSV Data Encoding and Response]]<br />
#* [[DAP4 Extension: NetCDF Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]</div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10527OPULS Development2014-04-21T23:20:00Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
<br />
This section is deprecated in favor of the top-level [[DAP4 Specification |DAP4 Specification page]].<br />
<br />
<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: CSV Data Encoding and Response]]<br />
#* [[DAP4 Extension: NetCDF Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10468DAP4 Extension: CSV Data Encoding and Response2014-03-21T00:38:57Z<p>EthanDavis: </p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This document specifies the DAP4 CSV data encoding, how DAP4 servers can advertise support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses.<br />
<br />
The DAP4 CSV data encoding represents DAP4 data as structured Comma-Separated Values (CSV) in UTF-8 text. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can fully represent the more complex data structures of the DAP4 data model. Some structure beyond simple CSV is necessary to capture the DAP4 data structures.<br />
<br />
As with requests for data in the DAP4 binary data encoding described in Volume 1 of the DAP4 specification <sup><nowiki>[</nowiki>[[#DAP4_Vol1|DAP4 Vol1]]<nowiki>]</nowiki></sup>, requests for DAP4 CSV encoded data can be constrained to a subset by using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
== DAP4 Extension Details ==<br />
<br />
The Role URI for the DAP4 CSV Data Encoding and Response extension is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/text-csv-data</nowiki>'''<br />
<br />
DAP4 servers MUST include this role URI in a Dataset Service Response [DSR] ''extension'' element to indicate that the DAP4 CSV Data Encoding and Response extension is supported for the dataset (?represented by that DSR?). DAP4 clients MAY check for DSR '''extension''' elements with this role URI to determine if the DAP4 CSV Data Encoding and Response extension is supported.<br />
<br />
Dataset Service Response [DSR] ''extension'' elements must also contain a name and a description. The following are recommended text for the name and description:<br />
<br />
<br />
;Name<br />
: DAP4 CSV Data Encoding and Response<br />
<br />
;Description <br />
: encoding represents DAP4 data as structured Comma-Separated Values (CSV) in UTF-8 text<br />
<br />
<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10467DAP4 Extension: CSV Data Encoding and Response2014-03-20T23:49:55Z<p>EthanDavis: </p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This document specifies the DAP4 CSV data encoding and its use with the DAP4 protocol.<br />
<br />
The DAP4 CSV data encoding represents DAP4 data<br />
<br />
requests can constrain the data to be returned using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
This DAP4 Extension describes the DAP4 CSV data encoding, the details needed so that a DAP4 server can advertise their support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can represent the more complex data structures of the DAP4 data model.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
Servers list supported DAP4 extensions in Dataset Service Response [DSR] ''extension'' elements. An ''extension'' element contains a name, role URI, and description.<br />
<br />
The Role URI for the DAP4 CSV Data Encoding is<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/extension/text-csv-data</nowiki>'''<br />
<br />
To advertise that a particular dataset supports the DAP4 CSV Data Encoding and Response encoding (i.e., data can be requested for that subset in the DAP4 CSV data encoding) support for the DAP4 CSV Data Encoding extension , a DAP4 server MUST include an ''extension'' element in a DSR<br />
<br />
A DAP4 server wishing to advertise support for the DAP4 CSV Data Encoding MUST list the following Role URI<br />
<br />
Name: DAP4 CSV Data Encoding<br />
<br />
Role URI:<br />
<br />
<br />
Description:<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10466OPULS Development2014-03-20T22:48:14Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: CSV Data Encoding and Response]]<br />
#* [[DAP4 Extension: netCDF Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_DAP4_CSV_Data_Encoding_and_Response&diff=10465DAP4 Extension: DAP4 CSV Data Encoding and Response2014-03-20T22:47:48Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: DAP4 CSV Data Encoding and Response to DAP4 Extension: CSV Data Encoding and Response</p>
<hr />
<div>#REDIRECT [[DAP4 Extension: CSV Data Encoding and Response]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10464DAP4 Extension: CSV Data Encoding and Response2014-03-20T22:47:48Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: DAP4 CSV Data Encoding and Response to DAP4 Extension: CSV Data Encoding and Response</p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
The DAP4 CSV data encoding represents DAP4 data<br />
<br />
requests can constrain the data to be returned using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
This DAP4 Extension describes the DAP4 CSV data encoding, the details needed so that a DAP4 server can advertise their support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can represent the more complex data structures of the DAP4 data model.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
Servers list supported DAP4 extensions in Dataset Service Response [DSR] ''extension'' elements. An ''extension'' element contains a name, role URI, and description.<br />
<br />
The Role URI for the DAP4 CSV Data Encoding is<br />
<br />
'''http://services.opendap.org/dap4/extension/text-csv-data'''<br />
<br />
To advertise that a particular dataset support for the DAP4 CSV Data Encoding extension , a DAP4 server MUST include an ''extension'' element in a DSR<br />
<br />
A DAP4 server wishing to advertise support for the DAP4 CSV Data Encoding MUST list the following Role URI<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
<br />
<br />
Description:<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10463OPULS Development2014-03-20T22:46:55Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: DAP4 CSV Data Encoding and Response]]<br />
#* [[DAP4 Extension: DAP4 netCDF Data Response]]<br />
#* [[DAP4 Extension: DAP4 Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Encoded_Data_Response&diff=10462DAP4 Extension: CSV Encoded Data Response2014-03-20T22:45:33Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: CSV Encoded Data Response to DAP4 Extension: DAP4 CSV Data Encoding and Response</p>
<hr />
<div>#REDIRECT [[DAP4 Extension: DAP4 CSV Data Encoding and Response]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10461DAP4 Extension: CSV Data Encoding and Response2014-03-20T22:45:33Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: CSV Encoded Data Response to DAP4 Extension: DAP4 CSV Data Encoding and Response</p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
The DAP4 CSV data encoding represents DAP4 data<br />
<br />
requests can constrain the data to be returned using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
This DAP4 Extension describes the DAP4 CSV data encoding, the details needed so that a DAP4 server can advertise their support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can represent the more complex data structures of the DAP4 data model.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
Servers list supported DAP4 extensions in Dataset Service Response [DSR] ''extension'' elements. An ''extension'' element contains a name, role URI, and description.<br />
<br />
The Role URI for the DAP4 CSV Data Encoding is<br />
<br />
'''http://services.opendap.org/dap4/extension/text-csv-data'''<br />
<br />
To advertise that a particular dataset support for the DAP4 CSV Data Encoding extension , a DAP4 server MUST include an ''extension'' element in a DSR<br />
<br />
A DAP4 server wishing to advertise support for the DAP4 CSV Data Encoding MUST list the following Role URI<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
<br />
<br />
Description:<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10460DAP4 Extension: CSV Data Encoding and Response2014-03-20T22:35:39Z<p>EthanDavis: </p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
The DAP4 CSV data encoding represents DAP4 data<br />
<br />
requests can constrain the data to be returned using a standard DAP4 Constraint Expression [DAP4 CE]<br />
<br />
This DAP4 Extension describes the DAP4 CSV data encoding, the details needed so that a DAP4 server can advertise their support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses. Though based on the ''text/csv'' media type described in <nowiki>RFC 4180</nowiki><sup><nowiki>[</nowiki>[[#RFC_4180|RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can represent the more complex data structures of the DAP4 data model.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
Servers list supported DAP4 extensions in Dataset Service Response [DSR] ''extension'' elements. An ''extension'' element contains a name, role URI, and description.<br />
<br />
The Role URI for the DAP4 CSV Data Encoding is<br />
<br />
'''http://services.opendap.org/dap4/extension/text-csv-data'''<br />
<br />
To advertise that a particular dataset support for the DAP4 CSV Data Encoding extension , a DAP4 server MUST include an ''extension'' element in a DSR<br />
<br />
A DAP4 server wishing to advertise support for the DAP4 CSV Data Encoding MUST list the following Role URI<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
<br />
<br />
Description:<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].<br />
<br />
<div id="DAP4_Extensions"></div><br />
<nowiki>[DAP4 Extensions]</nowiki> [DAP4:_Specification_Volume_1#Extensions|DAP4 Volume 1, Section 9.3 Extensions]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10459DAP4 Extension: CSV Data Encoding and Response2014-03-20T22:12:11Z<p>EthanDavis: </p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This DAP4 Extension describes the DAP4 CSV data encoding, how DAP4 servers advertise their support for the DAP4 CSV encoding, and how DAP4 clients can request DAP4 CSV encoded data responses. Though based on the text/csv media type described in RFC 4180<sup><nowiki>[</nowiki>[[#RFC_4180 | RFC 4180]]<nowiki>]</nowiki></sup>, the DAP4 CSV is more complex so that it can represent the more complex data structures of the DAP4 data model.<br />
<br />
== DAP4 Extension Details ==<br />
<br />
how DAP4 servers can advertise support for Text/CSV encoded data responses and how DAP4 clients can request Text/CSV encoded data responses.<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
http://services.opendap.org/dap4/extension/text-csv-data<br />
<br />
Description:<br />
<br />
== Requesting DAP4 CSV Encoded Data Response ==<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''" or "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: DAP4 CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; text/csv<br />
: DAP4 CSV (UTF-8) Data encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote><br />
<br />
== DAP4 CSV Encoding ==<br />
<br />
== Normative References ==<br />
<br />
<div id="RFC_4180"></div><br />
<nowiki>[RFC 4180]</nowiki> [https://www.ietf.org/rfc/rfc4180.txt Common Format and MIME Type for Comma-Separated Values (CSV) Files]<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4 Vol1]</nowiki> [[DAP4:_Specification_Volume_1|DAP4 Volume 1: Data Model, Persistent Representations, and Constraints]].</div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10458OPULS Development2014-03-20T21:40:50Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: CSV Encoded Data Response]]<br />
#* [[DAP4 Extension: netCDF Encoded Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_Text/CSV_Encoded_Data_Response&diff=10457DAP4 Extension: Text/CSV Encoded Data Response2014-03-20T21:40:12Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: Text/CSV Encoded Data Response to DAP4 Extension: CSV Encoded Data Response: DAP4 CSV but not necessarily the text/csv media type</p>
<hr />
<div>#REDIRECT [[DAP4 Extension: CSV Encoded Data Response]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10456DAP4 Extension: CSV Data Encoding and Response2014-03-20T21:40:10Z<p>EthanDavis: EthanDavis moved page DAP4 Extension: Text/CSV Encoded Data Response to DAP4 Extension: CSV Encoded Data Response: DAP4 CSV but not necessarily the text/csv media type</p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This DAP4 Extension document describes how DAP4 servers can advertise support for Text/CSV encoded data responses and how DAP4 clients can request Text/CSV encoded data responses.<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
http://services.opendap.org/dap4/extension/text-csv-data<br />
<br />
Description:<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: Text/CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki><br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Extension:_CSV_Data_Encoding_and_Response&diff=10455DAP4 Extension: CSV Data Encoding and Response2014-03-19T22:12:55Z<p>EthanDavis: Created page with " << Back to OPULS Development This DAP4 Extension document describes how DAP4 servers can advertise support for Text/CSV encoded data responses and how ..."</p>
<hr />
<div>[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
This DAP4 Extension document describes how DAP4 servers can advertise support for Text/CSV encoded data responses and how DAP4 clients can request Text/CSV encoded data responses.<br />
<br />
Name: Text/CSV Encoded Data Response<br />
<br />
Role URI:<br />
http://services.opendap.org/dap4/extension/text-csv-data<br />
<br />
Description:<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap.csv'''"<br />
|<br />
; application/vnd.opendap.dap4.data+csv<br />
: Text/CSV encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki><br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dap.csv'''<br />
|}<br />
</blockquote></div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10454OPULS Development2014-03-11T17:43:30Z<p>EthanDavis: /* DAP4 Specification */</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: Text/CSV Encoded Data Response]]<br />
#* [[DAP4 Extension: netCDF Encoded Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=OPULS_Development&diff=10453OPULS Development2014-03-11T16:46:34Z<p>EthanDavis: Adding links to extensions for text and netCDF encoded responses.</p>
<hr />
<div>== OPULS Process ==<br />
[[DAP4: Design Proposal Process| Design Proposal Process]]<br />
<br />
Short version: Each proposal is in one of the following categories:<br />
* New;<br />
* Under Consideration;<br />
* Accepted; <br />
* Declined;<br />
* Under Revision; or<br />
* Obsolete<br />
<br />
== DAP4 Specification ==<br />
The draft specification has two volumes.<br />
# [[DAP4: Overview | Overview: New Features Introduced in DAP4]]<br />
# [[DAP4: Specification Volume 1 | Volume 1: Data Model, Persistent Representation, and Constraints]]<br />
#* [[DAP4: Specification Volume 1 Deltas]]<br />
# [[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]<br />
# DAP4 Extensions<br />
#* [[DAP4 Extension: Text Encoded Data Response]]<br />
#* [[DAP4 Extension: netCDF Encoded Data Response]]<br />
#* [[DAP4 Extension: Asynchronous Response]]<br />
<br />
== DAP Use Cases ==<br />
As part of the DAP2 --> DAP4 transition process, we are soliciting ''use cases regarding DAP client application development'' from the community. If you'd like to submit a use case, you can send it to any of the OPULS developers (e.g., [mailto:jgallagher@openadp.org James Gallagher]) or the [mailto:opendap-tech@opendap.org OPeNDAP technical discussion list]. If you'd like you use case to be anonymous, that's fine, just let us know.<br />
<br />
We will use these use cases to spot likely problems that may be encountered by members of the community who have developed specific client applications that interact with DAP servers.<br />
<br />
=== Use cases from GSFC ===<br />
These use cases were submitted by Chris Lynnes:<br />
<br />
;Use Case #1: Spatial/Variable Subsetter. Our Simple Subset Wizard (SSW) works by constructing URLs to download spatial / variable subsets from the server as netCDF files (http://disc.gsfc.nasa.gov/SSW). This has allowed us to stop writing custom subsetter programs for each dataset or group of datasets.<br />
<br />
;Use Case #2: Giovanni (http://giovanni.gsfc.nasa.gov/giovanni/) provides data exploration capabilities for datasets from GES DISC as well as a few select other providers. Data are acquired from servers via OPeNDAP, saved as netCDF/CF1, which is the Giovanni internal standard. This allows the deployment of many netCDF-capable tools for analysis and data manipulation purposes.<br />
<br />
;Use Case #3: MapServer provides WMS services for GES DISC data. Rather than site individual instances on each data server, we use the .vrt (Virtual files) capability in MapServer to set up the OPeNDAP connections needed to acquire data for the MapServer.<br />
<br />
;Use Case #4: We are currently experimenting with the NcML aggregation capability to see if it is feasible to offer the ability to generate time series at a point using just Hyrax and the NcML handler.<br />
<br />
== DAP4 Features Straw man ==<br />
This is a straw man design, broken down into sections. It is incomplete and its content is subject to revision. <font color="red">This was our foil; don't use it.</font> The two documents about under 'DAP Specification' are the current state of the DAP4 specification.<br />
<br />
#<del> [[DAP4: DAP Versions | Versions]]</del><br />
# <del> [[DAP4: Checksum | Checksum]]</del><br />
# <del> [[DAP Service Terminus]]</del><br />
# <del> [[DAP4: Data Model | Data Model]] and a [http://scm.opendap.org/trac/browser/trunk/xml/dap/dap4.xsd XML Schema] that provides one representation for the data model.</del><br />
# <del> [[DAP4: Requests | Requests ]]</del><br />
# <del> [[DAP4: Responses | Responses]]</del><br />
# <del> [[DAP4_Web_Services_-_StartingPoint | Web Services (Starting Point)]]</del><br />
<br />
== Proposals ==<br />
<br />
===Data model ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ DAP4 Data Model Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: DAP4 Grids Proposal | Grids Ideas]] <br />
| '''Accepted''' <br />
| Dennis, et al. <br />
| (Cleaned up 4/10/2012)<br />
|-<br />
| [[DAP4: DAP4 XML| XML Use in DAP4]]<br />
| '''Accepted''' <br />
| Dennis <br />
| 2/25/2012<br />
|-<br />
| [[DAP4: Top Level Group | Top Level Group]]<br />
| '''Accepted'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Proposal for Keys in Sequences| Proposal for Supporting Keys in Sequences]]<br />
| '''Revised'''<br />
| Dennis<br />
| 5/28/2012<br />
|-<br />
| [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] <br />
| '''Under Consideration''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]''<br />
| James & Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] <br />
| '''Under Consideration'''<br />
| Dennis <br />
| 02/25/2012<br />
|-<br />
| [[DAP4: DAP4 Paths| Path Specification in DAP4]] <br />
| '''New'''<br />
| Dennis<br />
| 3/30/2012<br />
|-<br />
| [[DAP4: Coordinate Systems Element| Coordinate Systems Element]]<br />
| '''New''' <br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: Nested Attributes | Nested Attributes]]<br />
| '''New'''<br />
| Dennis<br />
| 4/12/2012<br />
|-<br />
| [[DAP4: Subsetting Arrays and Grids By Value| Subsetting Arrays and Grids By Value]]<br />
| '''New'''<br />
| Nathan<br />
| 4/27/2012<br />
|-<br />
| [[DAP4: Proposal for a Constraint Notation| Proposal for a Constraint Notation]]<br />
| '''New'''<br />
| Dennis<br />
| 4/30/2012<br />
|-<br />
| [[DAP4: Proposal for an abstract Constraint specification| Proposal for an Abstract Constraint Specification]]<br />
| '''New'''<br />
| James, ed.<br />
| 5/22/2012<br />
|-<br />
| [[DAP4: Proposal for Structure Projection| Proposal for Structure Projection]]<br />
| '''New'''<br />
| Dennis<br />
| 5/1/2012<br />
|-<br />
| [[DAP4: DAP4 Grids Ideas (Old Version) | Old Version of Grids Proposal]] <br />
| '''Obsolete'''<br />
| Dennis<br />
| 4/10/2012<br />
|-<br />
| [[DAP4: DAP4 Filter Constraints| Filter Constraints]] <br />
| '''new'''<br />
| Dennis, John, Ethan<br />
| 9/17/2012<br />
|-<br />
| [[DAP4: DAP4 Constraint Expressions| Constraint Expressions]] <br />
| '''new'''<br />
| Everyone; original note by Dennis, ed. by James<br />
| 10/29/2012<br />
|-<br />
| [[DAP4: DAP4 Projection Syntax| DAP4 Projection Syntax]]<br />
| '''withdrawn'''<br />
| Dennis<br />
| 2/8/2013<br />
|-<br />
| [[DAP4: DAP4 Checksum Changes| Proposed Changes to Checksumming]]<br />
| '''accepted with modifications 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: VLEN proposal| Proposal for new VLEN representation]]<br />
| '''New'''<br />
| Dennis<br />
| 7/21/2013<br />
|-<br />
| [[DAP4: Constraint Expressions, v2| Proposal for a Comprehensive Constraint Expression Syntax]]<br />
| '''New'''<br />
| James, Dennis, et al.<br />
| 7/29/2013<br />
|-<br />
| [[DAP4: Alternate Proposal for a Constraint Expression Syntax| Alternate Proposal for a Constraint Expression Syntax]]<br />
| '''New'''<br />
| Dennis<br />
| 10/16/2013<br />
|}<br />
<br />
=== Responses Specific to DAP4 ===<br />
{| class="wikitable" width="85%"<br />
|+ Persistent Representation<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4 Error Response| Error Response]]<br />
| '''new'''<br />
| Nathan<br />
| 11/19/2013<br />
|-<br />
| [[DAP4: DAP4 Using Multi-part Mime| Proposal to use Multi-part Mime]]<br />
| '''new 3/19/2013'''<br />
| Dennis<br />
| 3/1/2013<br />
|-<br />
| [[DAP4: Inclusion of response metadata in the DMR]]<br />
| '''New'''<br />
| James<br />
| 7/23/2013<br />
|-<br />
| [[DAP4: DDX Grammar | DAP4 DDX Grammar]] <br />
| '''Under Consideration'''<br />
| Dennis<br />
| <br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DDX Lexical Elements]] <br />
| '''Accepted''' <br />
| Dennis<br />
| 2/28/2012<br />
|-<br />
| [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] <br />
| '''Accepted'''<br />
| Dennis<br />
| 4/5/2012<br />
|-<br />
| [[DAP4: Encoding for the Data Response]] <br />
|'''Accepted''' <br />
| James, based on [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] by Dennis<br />
| 6/5/2012, updated 8/31/12<br />
|-<br />
| [[DAP4: Chunked encoding]] <br />
|'''Accepted''' <br />
| James<br />
| 6/8/2012, updated 8/31/12<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: DAP4 On the Wire Format | Proposed DAP4 On-The-Wire Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Multipart Mime Format | Proposed Multipart Mime Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 4/8/2012<br />
|-<br />
| [[DAP4: DAP4 Error Responses | Proposed Error Response Format]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 5/8/2012<br />
|-<br />
| [[DAP4: DAP4 Replacing Chunking | Proposal to Replace Chunking ]] <br />
|'''Obsolete''' <br />
| Dennis<br />
| 8/23/2012<br />
|}<br />
<br />
=== Web & HTTP ===<br />
<br />
{| class="wikitable" width="85%"<br />
|+ Web Service Proposals<br />
! Proposal<br />
! Status<br />
! Author<br />
! Date Proposed<br />
|-<br />
| [[DAP4: Constraint and Query | DAP4 Constraint expressions and query strings.]]<br />
| '''Under Consideration'''<br />
| Nathan Potter<br />
| 09/24/2012<br />
|-<br />
| [[DAP4: Possible Notation for Server Commands | Possible Notation for Server Commands]] <br />
|'''New''' <br />
| Dennis<br />
| Modified 04/12/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| [[DAP4: Asynchronous Request-Response Proposal v3 | DAP4 Asynchronous Request-Response Proposal (new new version)]]<br />
| '''Accepted'''<br />
| Ethan Davis and Nathan Potter and James Gallagher<br />
| 6/15/2012; updated 1 Aug 2012<br />
|-<br />
| <del>[[DAP4 Web Services v3 | DAP4 Web Services Proposal version 3]]</del><ins>[[DAP4: Specification Volume 2 | Volume 2: Web Services Specification]]</ins><br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/18/2012<br />
|-<br />
| [[DAP4 Dataset Services Response ]]<br />
| '''Accepted'''<br />
| Nathan Potter<br />
| 6/19/2012<br />
|-<br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
| <hr/><br />
|-<br />
| <del>[[DAP4: Asynchronous Responses | Asynchronous Responses]] </del><br />
| <del>'''Obsolete'''</del><br />
| <del>Nathan</del><br />
| <del>4/5/2012</del><br />
|-<br />
|<del> [[DAP4: Asynchronous Request-Response Proposal | DAP4 Asynchronous Request-Response Proposal]]</del><br />
|<del> '''Obsolete'''</del><br />
|<del> EthanDavis</del><br />
|<del> 4/10/2012</del><br />
|-<br />
| <del>[[DAP4: Capabilities and Versioning | DAP4 Capabilities and Versioning]]</del><br />
| <del>'''Obsolete'''</del><br />
| <del>EthanDavis</del><br />
| <del>4/10/2012</del><br />
|}<br />
<br />
<br />
<br />
<br />
<br />
<!--<br />
DAP4_Web_Services<br />
These proposals have been put forth by Dennis ([[User:Jimg|Jimg]] 15:18, 27 March 2012 (PDT) Ordered by priority at the 3/27/12 meeting):<br />
# [[DAP4: Constraints and Shared Dimensions | Constraints and Shared Dimensions]] '''Under Review''', ''closely related to [[DAP4: DAP4 Grids Proposal | Grids Ideas]]'' (New 02/26/2012)<br />
# [[DAP4: VLens (and Sequences)|Ideas for Defining VLens (and Sequences)]] '''Under Consideration''' (New 02/25/2012)<br />
# [[DAP4: DAP4 Paths| Path Specification in DAP4]] '''New''' (New 3/30/2012)<br />
# [[DAP4: DAP4 Escapes| Character Escape Mechanisms in DAP4]] '''New''' (Modified 4/5/2012)<br />
# [[DAP4: Asynchronous Responses | Asynchronous Responses]] '''New''' (New 4/5/2012)<br />
# [[DAP4: Coordinate Systems Element| Coordinate Systems Element]] '''New''' (New 4/10/2012)<br />
--><br />
<br />
== Commentary on DAP4 Related Topics ==<br />
These are not intended as specific proposal, but rather<br />
as commentary on some issues with DAP4 that need addressing<br />
with specific proposals.<br />
# [[DAP4: URL Annotations | Characterization of URL Annotations]] (Modified: 2/26/2012)<br />
# [[DAP4: Constructing a DDX from a Query | Constructing a DDX from a Query]] (new: 04/12/2012)<br />
# [[DAP4: Notes on Constraints | Notes on Constraints]] (new: 04/29/2012)<br />
# [[DAP4: An Essay on Domain Specific Models]] (new: 05/05/2012)<br />
<br />
== OPULS Implementation Thoughts ==<br />
=== Unidata's Current Thoughts ===<br />
<br />
Unidata needs:<br />
<br />
1) DAP4 C client library for use in netCDF-C library<br />
2) DAP4 Java client library for use in netCDF-Java library<br />
3) DAP4 Java server library for use in TDS<br />
4) Conformance test service against which a DAP4 client library can<br />
be tested<br />
5) Conformance test service against which a DAP4 server can be<br />
tested<br />
<br />
The current CDM and TDS use of opendap-java library has performance<br />
problems due to extra API layers and extra copying of data. We would<br />
prefer direct serialization between CDM objects and the DAP<br />
on-the-wire data and would recommend that the OPeNDAP Java library<br />
leverage the netCDF-Java libraries.<br />
<br />
If there are needs that the DAP4 opendap-java library be independent<br />
of the netCDF-Java library, then in order for CDM and TDS to use the<br />
opendap-java library, we would need the performance concerns mentioned<br />
above addressed. A reasonable metric would be within some percentage<br />
of cdmremote[1], say within 20-25%.<br />
<br />
Unidata's performance requirements for Java libraries:<br />
<br />
1) The netCDF-Java library performance reading DAP4 through the DAP4<br />
Java client library must perform within 20-25% of cdmremote [1].<br />
2) TDS performance when handling DAP4 requests using the DAP4 Java<br />
server library should perform within 20-25% of cdmremote [1].<br />
<br />
We believe this means that the DAP4 Java libraries must provide a<br />
sufficiently generic API that can be used directly with the CDM/TDS<br />
IOSP interface.<br />
<br />
Unidata will:<br />
1) Write the DAP4 C client library.<br />
2) ??? some part of Java server library<br />
3) ??? some parts of conformance testing services<br />
<br />
NOTES:<br />
<br />
[1] cdmremote is an experimental CDM streaming service. It is basically<br />
a direct serialization of the CDM.<br />
== OPULS references ==<br />
* http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown<br />
<br />
== Old DAP4 Design and Implementation ==<br />
* [[DAP3/4]]<br />
* [[DAP 4.0 Design]] and [[DAP 4.0 Essential Features]] The ''design'' is meant to be a complete document while ''essential features'' are the minimal see we want to release. Since this task has been stalled for nearly a year, doing the latter seems like a noble goal.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4:_DAP4_Checksum_Changes&diff=9565DAP4: DAP4 Checksum Changes2013-03-06T23:38:47Z<p>EthanDavis: /* Discussion */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
[Updated: 3/5/2013 to reflect conversation with Ethan. See discussion section.]<br />
<br />
==Background==<br />
Currently, the specification says that checksums<br />
are computed on the contents of the top-level variables<br />
in the serialized response. I propose that we change<br />
when and where the checksum is computed so that it is<br />
computed at the grain of the data chunks instead of at<br />
the grain of variable.<br />
<br />
==Problem Addressed==<br />
Checksumming currently requires knowledge of the<br />
DMR (and potentially any constraints) so that<br />
the contents of "top-level" variables can be identified<br />
in the data serialization. Further, checksum errors are<br />
not detected until the whole variable has been read.<br />
<br />
==Proposed Solution==<br />
<br />
===General Format===<br />
Each chunk, including the DMR meta-data chunk,<br />
has a 16 byte MD5 checksum preceding the contents of the chunk,<br />
but following the length count for the chunk.<br />
Thus, the general form of a chunk would be as follows:<br />
<pre><br />
--------------------------<br />
| length + tags [4bytes] |<br />
--------------------------<br />
| checksum [16 bytes] |<br />
--------------------------<br />
| data [length-16 bytes] |<br />
--------------------------<br />
</pre><br />
The checksum is computed over the contents of the chunk, where the<br />
content is treated as uninterpreted bytes. This would also apply to<br />
the DMR chunk. The length field for each chunk includes the checksum<br />
as part of its length.<br />
<br />
===DMR Format===<br />
In keeping with our current format for the DMR chunk,<br />
all parts of this chunk are encoded as UTF-8 characters<br />
So the general DMR chunk format would be as follows<br />
<pre><br />
------------------------------------------<br />
| 0xHHHHHHHH CRLF |<br />
------------------------------------------<br />
| 0xHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH CRLF |<br />
------------------------------------------<br />
| DMR in XML format CRLF |<br />
------------------------------------------<br />
</pre><br />
Each 'H' stands for a hex digit.<br />
As in the general case, the length includes the checksum<br />
and the chunk content (i.e. the DMR).<br />
<br />
==Discussion==<br />
Computing the checksum at the chunk level<br />
simplifies processing because no knowledge<br />
of the DMR is required. The computation can be<br />
carried out completely<br />
in the chunk reading and writing code.<br />
<br />
Additionally, computing the checksum at the<br />
chunk level can potentially detect errors more<br />
quickly than at the variable level. To see this,<br />
suppose that a variable crosses, say, three chunks,<br />
and there is an error in the first chunk.<br />
If variable level grain is used, three chunks will be<br />
read an processed before the checksum error is detected.<br />
If chunk grain is used, then the error will be detected<br />
as soon as the first chunk is read; the following two chunks<br />
need not be processed.<br />
<br />
This proposal also introduces no new error processing complexity<br />
because a checksum error at the chunk level will generate an<br />
IOException error to the layers above. These layers must already<br />
be prepared to receive IOException errors such as when, for example, the<br />
client-server link is unexpectedly closed.<br />
<br />
[[User:dmh|Dennis]]<br />
<br />
<blockquote><br />
It was my understanding that checksums were introduced into the specification not as a mechanism for insuring error free data transmittal (although that is a side benefit) but as a mechanism through which clients can detect changes (or the lack thereof) in data content. For example a data provider might reprocess their data holdings because more refined algorithms have become available, but not all variables in the dataset may be affected (thus the last-modified time of the holding is not necessarily the best indicator, at the variable level, of what's going on). If my understanding is accurate I'm thinking that this proposal fails to meet the requirements regarding change tracking at the variable level. If I am wrong, and checksums are all about error free transport, then at first read I think that this is a reasonable change.<br><br />
[[User:Ndp|ndp]] 15:44, 1 March 2013 (PST)<br />
</blockquote><br />
<br />
Update: 5/3/2013 [[User:dmh|Dennis]]<br><br />
Nathan, you are correct. Ethan made a similar comment.<br />
However, in order to make this usable, we need to provide<br />
a standard mechanism by which the client can access the checksum.<br />
I propose that we add a specially named attribute in the DMR<br />
that holds the checksum value for a variable. I propose that<br />
the attribute be named "_<checksum algorithm>". So if we are using<br />
MD5, the attribute is called "_MD5" [see next update].<br />
<br />
The question now becomes: do we need to add any kind of error checking<br />
checksumming or do rely on network reliability. Note that using<br />
a checksum only for change detection does not require the client to actually<br />
recompute the checksum; it only needs to display it to the user's code<br />
(via e.g. an attribute).<br />
<br />
Update: 5/3/2013 [[User:dmh|Dennis]]<br><br />
It is not obvious why we should be defaulting to MD5<br />
as the checksum algorithm. If we were doing this to<br />
avoid man-in-the-middle spoofing, we should be using SHA1.<br />
If our goal is change detection (or even error detection),<br />
then we can get by with, say, CRC32, which is both smaller<br />
and faster than MD5. The corresponding attribute (see previous update)<br />
would be "_CRC32".<br />
<br />
[[User:Jimg|Jimg]] 11:51, 6 March 2013 (PST)<br><br />
The original use case was ''change detection'' and I think that should remain the primary focus. If we can get additional functionality out of the checksum without additional cost, that would be great. Thus using CRC32 would be the best choice (I used MD5 because it was the first hash algorithm that came to mind, and it was easy to use from a library that's on both Linux and OS/X). Faster is better! And I like very much the idea of adding an attribute for the information, because it is important that the information be available to clients/users. So lets make these changes to the specification. <br />
<br />
NB: In our discussions added ''error detection,'' but I'm not sure that's a high priority, and if the CRC code is present as an attribute, then clients can use it for error detection if their developers want to code that.<br />
<br />
--[[User:EthanDavis|EthanDavis]] 15:27, 6 March 2013 (PST)<br />
<br />
What is the granularity of change detection we want to support?<br />
<br />
Given the cross-server aspect of the [[DAP4:_Checksum#Use_cases|original use case]], I understand the use of checksums in the [[DAP4:_Checksum#Requirements|requirements list]]. But why is per variable checksums included? I'm not seeing variable level change detection mentioned in the use case.<br />
<br />
Sure, it would be cool if those who want could figure out exactly which variable had changed. But is that really something that will be widely used?<br />
<br />
Perhaps we should restrict this discussion to dataset level change detection. And postpone it for DAP4 objects below the dataset level.<br />
<br />
--[[User:EthanDavis|EthanDavis]] 15:38, 6 March 2013 (PST) <br><br />
By the way, what bytes are we going to use to compute a checksum? The files on disk, the bytes of an array in memory, the DAP4 encoded objects? Or should we leave that up to each server and server site configuration to decide?</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4:_DAP4_Checksum_Changes&diff=9564DAP4: DAP4 Checksum Changes2013-03-06T23:27:47Z<p>EthanDavis: /* Discussion */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
<br />
[Updated: 3/5/2013 to reflect conversation with Ethan. See discussion section.]<br />
<br />
==Background==<br />
Currently, the specification says that checksums<br />
are computed on the contents of the top-level variables<br />
in the serialized response. I propose that we change<br />
when and where the checksum is computed so that it is<br />
computed at the grain of the data chunks instead of at<br />
the grain of variable.<br />
<br />
==Problem Addressed==<br />
Checksumming currently requires knowledge of the<br />
DMR (and potentially any constraints) so that<br />
the contents of "top-level" variables can be identified<br />
in the data serialization. Further, checksum errors are<br />
not detected until the whole variable has been read.<br />
<br />
==Proposed Solution==<br />
<br />
===General Format===<br />
Each chunk, including the DMR meta-data chunk,<br />
has a 16 byte MD5 checksum preceding the contents of the chunk,<br />
but following the length count for the chunk.<br />
Thus, the general form of a chunk would be as follows:<br />
<pre><br />
--------------------------<br />
| length + tags [4bytes] |<br />
--------------------------<br />
| checksum [16 bytes] |<br />
--------------------------<br />
| data [length-16 bytes] |<br />
--------------------------<br />
</pre><br />
The checksum is computed over the contents of the chunk, where the<br />
content is treated as uninterpreted bytes. This would also apply to<br />
the DMR chunk. The length field for each chunk includes the checksum<br />
as part of its length.<br />
<br />
===DMR Format===<br />
In keeping with our current format for the DMR chunk,<br />
all parts of this chunk are encoded as UTF-8 characters<br />
So the general DMR chunk format would be as follows<br />
<pre><br />
------------------------------------------<br />
| 0xHHHHHHHH CRLF |<br />
------------------------------------------<br />
| 0xHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH CRLF |<br />
------------------------------------------<br />
| DMR in XML format CRLF |<br />
------------------------------------------<br />
</pre><br />
Each 'H' stands for a hex digit.<br />
As in the general case, the length includes the checksum<br />
and the chunk content (i.e. the DMR).<br />
<br />
==Discussion==<br />
Computing the checksum at the chunk level<br />
simplifies processing because no knowledge<br />
of the DMR is required. The computation can be<br />
carried out completely<br />
in the chunk reading and writing code.<br />
<br />
Additionally, computing the checksum at the<br />
chunk level can potentially detect errors more<br />
quickly than at the variable level. To see this,<br />
suppose that a variable crosses, say, three chunks,<br />
and there is an error in the first chunk.<br />
If variable level grain is used, three chunks will be<br />
read an processed before the checksum error is detected.<br />
If chunk grain is used, then the error will be detected<br />
as soon as the first chunk is read; the following two chunks<br />
need not be processed.<br />
<br />
This proposal also introduces no new error processing complexity<br />
because a checksum error at the chunk level will generate an<br />
IOException error to the layers above. These layers must already<br />
be prepared to receive IOException errors such as when, for example, the<br />
client-server link is unexpectedly closed.<br />
<br />
[[User:dmh|Dennis]]<br />
<br />
<blockquote><br />
It was my understanding that checksums were introduced into the specification not as a mechanism for insuring error free data transmittal (although that is a side benefit) but as a mechanism through which clients can detect changes (or the lack thereof) in data content. For example a data provider might reprocess their data holdings because more refined algorithms have become available, but not all variables in the dataset may be affected (thus the last-modified time of the holding is not necessarily the best indicator, at the variable level, of what's going on). If my understanding is accurate I'm thinking that this proposal fails to meet the requirements regarding change tracking at the variable level. If I am wrong, and checksums are all about error free transport, then at first read I think that this is a reasonable change.<br><br />
[[User:Ndp|ndp]] 15:44, 1 March 2013 (PST)<br />
</blockquote><br />
<br />
Update: 5/3/2013 [[User:dmh|Dennis]]<br><br />
Nathan, you are correct. Ethan made a similar comment.<br />
However, in order to make this usable, we need to provide<br />
a standard mechanism by which the client can access the checksum.<br />
I propose that we add a specially named attribute in the DMR<br />
that holds the checksum value for a variable. I propose that<br />
the attribute be named "_<checksum algorithm>". So if we are using<br />
MD5, the attribute is called "_MD5" [see next update].<br />
<br />
The question now becomes: do we need to add any kind of error checking<br />
checksumming or do rely on network reliability. Note that using<br />
a checksum only for change detection does not require the client to actually<br />
recompute the checksum; it only needs to display it to the user's code<br />
(via e.g. an attribute).<br />
<br />
Update: 5/3/2013 [[User:dmh|Dennis]]<br><br />
It is not obvious why we should be defaulting to MD5<br />
as the checksum algorithm. If we were doing this to<br />
avoid man-in-the-middle spoofing, we should be using SHA1.<br />
If our goal is change detection (or even error detection),<br />
then we can get by with, say, CRC32, which is both smaller<br />
and faster than MD5. The corresponding attribute (see previous update)<br />
would be "_CRC32".<br />
<br />
[[User:Jimg|Jimg]] 11:51, 6 March 2013 (PST)<br><br />
The original use case was ''change detection'' and I think that should remain the primary focus. If we can get additional functionality out of the checksum without additional cost, that would be great. Thus using CRC32 would be the best choice (I used MD5 because it was the first hash algorithm that came to mind, and it was easy to use from a library that's on both Linux and OS/X). Faster is better! And I like very much the idea of adding an attribute for the information, because it is important that the information be available to clients/users. So lets make these changes to the specification. <br />
<br />
NB: In our discussions added ''error detection,'' but I'm not sure that's a high priority, and if the CRC code is present as an attribute, then clients can use it for error detection if their developers want to code that.<br />
<br />
--[[User:EthanDavis|EthanDavis]] 15:27, 6 March 2013 (PST)<br />
<br />
What is the granularity of change detection we want to support?<br />
<br />
Given the cross-server aspect of the [[DAP4:_Checksum#Use_cases|original use case]], I understand the use of checksums in the [[DAP4:_Checksum#Requirements|requirements list]]. But why is per variable checksums included? I'm not seeing variable level change detection mentioned in the use case.<br />
<br />
Sure, it would be cool if those who want could figure out exactly which variable had changed. But is that really something that will be widely used?<br />
<br />
Perhaps we should restrict this discussion to dataset level change detection. And postpone it for DAP4 objects below the dataset level.</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9434DAP4 Web Services v32012-09-26T23:00:50Z<p>EthanDavis: /* Introduction */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response (DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response (DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 protocol uses a fifth basic resource, the Error Response (ER), to allow servers to communicate error information with clients. When a request for any of the three basic responses cannot be completed, an Error response is returned. If an error occurs before the standard response is initiated, an error response is returned in place of the standard response. If an error occurs after a data response has been initiated, an Error Response is returned as the final chunked record as described in Section 7 "DAP4 Chunked Data Representation" of the DAP4 Data Model document <nowiki>[</nowiki>[[#DAP4_Vol1|DAP4_Vol1]]<nowiki>]</nowiki>.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document <nowiki>[</nowiki>[[#DAP4_Vol1|DAP4_Vol1]]<nowiki>]</nowiki>.<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
'''Dataset Services Response (DSR)'''<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="text-align: left;"| Resource Role<br />
|-<br />
|<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
|}<br />
<br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "" or "'''.dsr'''"<br />
|<br />
; application/vnd.opendap.org.dap4.dataset-services+xml<br />
: Normative DSR encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki><br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dsr'''<br />
|-<br />
| "'''.xml'''" or "'''.dsr.xml'''"<br />
|<br />
; text/xml<br />
: Normative DSR encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.xml'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dsr.xml'''<br />
|-<br />
| "'''.html'''" or "'''.dsr.html'''"<br />
|<br />
; text/html<br />
: HTML DSR encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.html'''<br />
<nowiki>http://server/path/dataset.nc</nowiki>'''.dsr.html'''<br />
|}<br />
</blockquote><br />
<br />
'''Dataset Metadata Response (DMR)'''<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="text-align: left;"| Resource Role<br />
|-<br />
|<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki>'''<br />
|}<br />
<br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dmr'''"<br />
|<br />
; application/vnd.opendap.org.dap4.dataset-metadata+xml<br />
: Normative DMR encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dmr'''<br />
|-<br />
| "'''.dmr.xml'''"<br />
|<br />
; text/xml<br />
: Normative DMR encoding with generic media type<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dmr.xml'''<br />
|-<br />
| "'''.dmr.html'''"<br />
|<br />
; text/html<br />
: HTML DMR encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dsr.html'''<br />
|}<br />
</blockquote><br />
<br />
'''Dataset Data Response (Data)'''<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="text-align: left;"| Resource Role<br />
|-<br />
|<br />
: '''<nowiki>http://services.opendap.org/dap4/data</nowiki>'''<br />
|}<br />
<br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| "'''.dap'''"<br />
|<br />
; application/vnd.opendap.org.dap4.data<br />
: Normative Data encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap'''<br />
|-<br />
| "'''.dap.txt'''"<br />
|<br />
; text/plain<br />
: Text (UTF-8) Data encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.txt'''<br />
|-<br />
| "'''.dap.xml'''"<br />
|<br />
; text/xml<br />
: XML Data encoding<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.dap.xml'''<br />
|}<br />
</blockquote><br />
<br />
'''Error Response (ER)'''<br />
<br />
<blockquote><br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="text-align: left;"| Resource Role<br />
|-<br />
|<br />
: '''<nowiki>http://services.opendap.org/dap4/error</nowiki>'''<br />
|}<br />
<br />
{| class="wikitable" style="font-size: 95%;" width="90%"<br />
! style="width: 15%" | URL Suffix<br />
! style="width: 55%" | Media Type<br />
! style="width: 30%" | URL Example<br />
|-<br />
| N/A<br />
|<br />
; application/vnd.opendap.org.dap4.error+xml<br />
: Normative Error encoding<br />
| N/A<br />
|-<br />
| N/A<br />
|<br />
; text/xml<br />
: Normative Error encoding with generic media type<br />
| N/A<br />
|-<br />
| N/A<br />
|<br />
; text/html<br />
: HTML Error encoding<br />
| N/A<br />
|}<br />
</blockquote><br />
<br />
<br />
=== DAP4 Core Specification Documents ===<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9433DAP4 Web Services v32012-09-26T21:44:31Z<p>EthanDavis: /* Introduction */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response (DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response (DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 protocol uses a fifth basic resource, the Error Response (ER), to allow servers to communicate error information with clients. When a request for any of the three basic responses cannot be completed, an Error response is returned. If an error occurs before the standard response is initiated, an error response is returned in place of the standard response. If an error occurs after a data response has been initiated, an Error Response is returned as the final chunked record as described in Section 7 "DAP4 Chunked Data Representation" of the DAP4 Data Model document [[#DAP4_Vol1|DAP4_Vol1]].<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|DAP4_Vol1]].<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
'''Dataset Services Response (DSR)'''<br />
<br />
Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
<br />
{| class="wikitable"<br />
!Media Type<br />
!Description<br />
!URL Extension<br />
!URL Example<br />
|-<br />
|'''application/vnd.opendap.org.dataset-services+xml'''<br />
|Normative DSR encoding<br />
|"" (none)<br />
|<nowiki>http://server/path/dataset.nc</nowiki><br />
|-<br />
|'''text/xml'''<br />
|Normative DSR encoding with generic media type<br />
| "'''.xml'''"<br />
|<nowiki>http://server/path/dataset.nc</nowiki>'''.xml'''<br />
|-<br />
|'''text/html'''<br />
| HTML encoding<br />
| "'''.html'''"<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.html'''<br />
|-<br />
|}<br />
<br />
; Dataset Services Response (DSR)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.dataset-services+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Metadata Response (DMR):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.dataset-metadata+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Data Response (Data):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/data</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.data'''<br />
:* '''text/plain''' (ASCII data response)<br />
:* '''text/xml''' (XML data response)<br />
<br />
; Error Response (ER)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/error</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.error+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9431DAP4 Web Services v32012-09-26T17:26:04Z<p>EthanDavis: /* Introduction */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response (DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response (DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 protocol uses a fifth basic resource, the Error Response (ER), to allow servers to communicate error information with clients. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place. If an error occurs while data is being transmitted, an Error Response is returned as the final chunked record as described ...<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
'''Dataset Services Response (DSR)'''<br />
<br />
Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
<br />
{| class="wikitable"<br />
!Media Type<br />
!Description<br />
!URL Extension<br />
!URL Example<br />
|-<br />
|'''application/vnd.opendap.org.dataset-services+xml'''<br />
|Normative DSR encoding<br />
|"" (none)<br />
|<nowiki>http://server/path/dataset.nc</nowiki><br />
|-<br />
|'''text/xml'''<br />
|Normative DSR encoding with generic media type<br />
| "'''.xml'''"<br />
|<nowiki>http://server/path/dataset.nc</nowiki>'''.xml'''<br />
|-<br />
|'''text/html'''<br />
| HTML encoding<br />
| "'''.html'''"<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.html'''<br />
|-<br />
|}<br />
<br />
; Dataset Services Response (DSR)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.dataset-services+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Metadata Response (DMR):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.dataset-metadata+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Data Response (Data):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/data</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.data'''<br />
:* '''text/plain''' (ASCII data response)<br />
:* '''text/xml''' (XML data response)<br />
<br />
; Error Response (ER)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/error</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.error+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9426DAP4 Web Services v32012-09-26T04:51:57Z<p>EthanDavis: /* DAP4 Resource Roles and Media Types */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
'''Dataset Services Response (DSR)'''<br />
<br />
Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
<br />
{| class="wikitable"<br />
!Media Type<br />
!Description<br />
!URL Extension<br />
!URL Example<br />
|-<br />
|'''application/vnd.opendap.org.dataset-services+xml'''<br />
|Normative DSR encoding<br />
|"" (none)<br />
|<nowiki>http://server/path/dataset.nc</nowiki><br />
|-<br />
|'''text/xml'''<br />
|Normative DSR encoding with generic media type<br />
| "'''.xml'''"<br />
|<nowiki>http://server/path/dataset.nc</nowiki>'''.xml'''<br />
|-<br />
|'''text/html'''<br />
| HTML encoding<br />
| "'''.html'''"<br />
| <nowiki>http://server/path/dataset.nc</nowiki>'''.html'''<br />
|-<br />
|}<br />
<br />
; Dataset Services Response (DSR)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.dataset-services+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Metadata Response (DMR):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.dataset-metadata+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
; Dataset Data Response (Data):<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/data</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.org.opendap.dap4.data'''<br />
:* '''text/plain''' (ASCII data response)<br />
:* '''text/xml''' (XML data response)<br />
<br />
; Error Response (ER)<br />
: Resource Role: '''<nowiki>http://services.opendap.org/dap4/error</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.error+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* '''text/html'''<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9425DAP4 Web Services v32012-09-26T04:17:37Z<p>EthanDavis: /* DAP4 Resource Roles and Media Types */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
'''Dataset Services Response (DSR)'''<br />
<br />
Resource Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
{| class="wikitable"<br />
|Media Type<br />
|Standard URL filename extension (example)<br />
|-<br />
|application/vnd.opendap.org.dataset-services+xml<br />
|none ("") -- (<nowiki>http://server/path/dataset.nc</nowiki>)<br />
|-<br />
|text/xml (same encoding as above but more generic media type)<br />
| ".xml" -- (<nowiki>http://server/path/dataset.nc.xml</nowiki>)<br />
|-<br />
|text/html<br />
| ".html" -- (<nowiki>http://server/path/dataset.nc.html</nowiki>)<br />
|-<br />
|}<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
: Standard URL filename extension:<br />
:* "": <nowiki>http://server/path/dataset</nowiki><br />
:* ".xml": <nowiki>http://server/path/dataset</nowiki>'''.xml'''<br />
:* ".html": <nowiki>http://server/path/dataset</nowiki>'''.html'''<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9423DAP4 Web Services v32012-09-25T23:34:36Z<p>EthanDavis: /* Introduction */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Media Types ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
: Standard URL filename extension:<br />
:* "": <nowiki>http://server/path/dataset</nowiki><br />
:* ".xml": <nowiki>http://server/path/dataset</nowiki>'''.xml'''<br />
:* ".html": <nowiki>http://server/path/dataset</nowiki>'''.html'''<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Dataset_Services_Response&diff=9312DAP4 Dataset Services Response2012-09-05T22:19:36Z<p>EthanDavis: /* Example Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
<br />
[[OPULS_Development | <-- back to OPULS Development]]<br />
<br />
Author: [[User:Ndp|ndp]]<br />
<br />
== Background ==<br />
<br />
DAP2, while successful within several arenas in the scientific community, failed to provide a complete description of the web interface that a server should support. This came about for two reasons: DAP2 was developed at a time when 'web services' was an idea in considerable flux and, secondly, the DAP2 specification was written to focus on a data model (mostly) that supported interoperability. The current DAP4 draft specification document, like the DAP2 specification, does not address how a web-based interface to DAP4 should be built. However, we are going to provide a specification that will describe how such an interface for DAP4 should be built and this document contains information that should be part of that specification.<br />
<br />
== Problem addressed ==<br />
<br />
Currently DAP2 servers provide a number of dataset level responses (services). These include DAP2 services such as the DDS, DAS, and DDX, plus other services that have been added over time such as the RDF and ISO responses. There is currently no way for a user (or software agent) to discover which of these many services might be available for a particular dataset. While THREDDS catalogs do provide a mechanism for determining which services are associated with which datasets, they don't actually provide a mechanism for discovering the details of the various service URLs. A THREDDS catalog might identify a DAP2 service, but the URL that can be assembled from the THREDDS catalog for that service is limited to just the base dataset URL. Typically dereferencing this URL will provide one of two things - either the underlying data file (for example a netcdf file) or an HTTP 403 error if direct access to the underlying files has been disabled in the server configuration.<br />
<br />
'''Example:'''<br />
<br />
This URL points to a dataset on a DAP2 server:<br />
<font size="2"><br />
http://test.opendap.org:8080/opendap/data/nc/fnoc1.nc<br />
</font><br />
<br />
Dereferencing the link will not connect you to a DAP2 service or DAP2 response. It will (likely) return the underlying netcdf file. The only way to know that DAP2 services exist for this is by reading the URL path and recognizing that it is probably an instance of a DAP2 server based on the composition of the URL. In fact, there is no guarantee that dereferencing this URL will even yield the underlying file, as that behavior is a configuration option for some server implementations. If that access is not allowed in the configuration, then dereferencing the URL will simply return an HTTP 403 (forbidden) error.<br />
<br />
== Proposed solution ==<br />
<br />
We intend to provide a 'Services' or 'Capabilities' response for DAP4. Dereferencing an unadorned DAP4 dataset resource URL will return a document describing the DAP services available for the dataset. This will be a required response and the only valid response for an 'unadorned' dataset resource URL. We will refer to this response as the 'Dataset Services Response' or 'DSR' in the 'DAP4 Web Services' specification and the remainder of this document. <br />
<br />
At minimum this document MUST provide, for each service available for the dataset:<br />
<br />
* A human readable title of that service (e.g., The DDX service for the dataset)<br />
* One or more links that can be dereferenced to get the various representations of the response for the dataset.<br />
* An unambiguous, unique to the service type, resource role ID that serves as a way to clearly identify what each service does.<br />
* A brief description of the service<br />
<br />
The response should also include:<br />
* A link to a complete, human readable, description of the service.<br />
* A reference to an XSLT that a browser would use to render the description into HTML for a presentation view.<br />
* Descriptions and syntax of server side functions available for the dataset<br />
<br />
=== Service Access ===<br />
<br />
A service is accessed by dereferencing one of the access URLs held in the <font size="2"><code>'''href'''</code></font> attribute of a <font size="2"><code>'''<dsr:link>'''</code></font> elements, 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.<br />
<br />
A more extensive discussion of the various services that might appear in a DatasetServices document can be found on the [[DAP4 Web Services v3]] page.<br />
<br />
'''Note:''' If a client understands how to modify/augment the dataset resource URL ( as described in the [[DAP4_Web_Services_v3#Web_Services | DAP4 Web Services Specification]] ) such that it becomes a DAP response URL then it need never obtain the Dataset Services response.<br />
<br />
=== Dataset Services Response Encoding === <br />
<br />
c.f. [[DAP4_Web_Services v3| DAP4 Web Services]]<br />
<br />
''In this section the namespace prefix <font size="2"><code>'''dsr'''</code></font> is associated with the namespace '''<font size="2"><code><nowiki>http://xml.opendap.org/ns/DAP/4.0/dataset-services#</nowiki></code></font>'''.''<br />
<br />
==== dsr:DatasetServices Element ====<br />
<br />
The Dataset Services Response MUST contain a top level <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element. This <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element MUST contain:<br />
* An <font size="2"><code>'''xml:base'''</code></font> attribute whose value is the resource URL that was dereferenced to request the DSR response.<br />
* A list of DAP versions supported by server<br />
*: These appear as one or more child <font size="2"><code>'''<dsr:DapVersion>'''</code></font> elements of the <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element.<br />
* The implementation version of the server that produced the DSR.<br />
*: This appears as a single <font size="2"><code>'''<dsr:ServerSoftwareVersion>'''</code></font> child element of the <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element. <br />
* A list of all available DAP4 services for the dataset<br />
*: This is represented as 3 or more <font size="2"><code>'''[[#Service_Element | <dsr:Service>]]'''</code></font> elements. (There are 3 required services for a DAP4 server.) <br />
* A list of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
The <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element SHOULD contain:<br />
* A <font size="2"><code>'''title'''</code></font> attribute whose value is a human readable title for the dataset.<br />
<br />
==== dsr:DapVersion Element ====<br />
The <font size="2"><code>'''<dsr:DapVersion>'''</code></font> element contains a single DAP version value as a text string. The DAP version is represented as two integer values separated by a period, MM.mm where the first value (MM) is the major version of the DAP protocol, and the second value (mm) is the minor version. Multiple <font size="2"><code>'''<dsr:DapVersion>'''</code></font> elements are used to represent that server can support multiple versions of the DAP protocol, one instance for each supported version.<br />
<br />
Example:<br />
<font size="2"><br />
<source lang="xml" ><br />
<DapVersion>4.0</DapVersion><br />
<DapVersion>3.2</DapVersion><br />
<DapVersion>2.0</DapVersion><br />
</source><br />
</font><br />
<br />
==== dsr:ServerSoftwareVersion Element ====<br />
<br />
The <font size="2"><code>'''<dsr:ServerSoftwareVersion>'''</code></font> element has no attributes and may contain as little as a simple text string (e.g., "TDS 4.3.57" or "Hyrax 1.7.45"), or it may contain any well-formed XML content not in the <font size="2"><code>'''dsr'''</code></font> namespace that the server implementer sees fit to use to describe the software version of their server implementation.<br />
<br />
==== dsr:Service Element ====<br />
<br />
Each DAP4 web service is described by a <font size="2"><code>'''<dsr:Service>'''</code></font> element with:<br />
* An optional <font size="2"><code>'''title'''</code></font> attribute whose value is a simple human readable title for the service. <br />
* An required <font size="2"><code>'''role'''</code></font> attribute whose value is a unique to the service type, resource role ID (a URI) that serves as a way to clearly identify what each service does. This is intended to allow people and software to unambiguously identify specific services, irrespective of their human readable title. The idea is that that the role attribute tells you what is going to happen when you dereference the URL held in the <font size="2"><code>'''<dsr:link>'''</code></font> element. Each service has a single role and all of the links (alternate representations) must fulfill the same role.<br />
* An optional <font size="2"><code>'''<dsr:Description>'''</code></font> element .<br />
* One or more <font size="2"><code>'''<dsr:link>'''</code></font> elements.<br />
<br />
===== Regarding the <font size="3"><code>'''role'''</code></font> attribute =====<br />
<br />
With regards to multiple representations of a service response and the <font size="2"><code>'''role'''</code></font> attribute: While there may be many alternate representations of a response, not all will fufill the same <font size="2"><code>'''role'''</code></font>. Representations fulfilling the same <font size="2"><code>'''role'''</code></font> should be bundled together in their own '''Service''' with the appropriate <font size="2"><code>'''role'''</code></font> value. For example the DMR can be mapped to the ISO19115 metadata space, but IS0-19115 responses are clearly outside of the <font size="2"><code>'''role'''</code></font> of the regular DMR service, which returns a DAP4 metadata response. One could view it as the two roles described different domains.<br />
<br />
==== dsr:Description Element ====<br />
Each <font size="2"><code>'''<dsr:Description>'''</code></font> element MUST contain:<br />
* An optional <font size="2"><code>'''href'''</code></font> attribute whose value is a URL string that points to a human readable document describing the service. <br />
* The required text content of the <font size="2"><code>'''dsr:Description'''</code></font> element MUST be a human readable description of the service.<br />
<br />
==== dsr:link Element ====<br />
<br />
Each <font size="2"><code>'''<dsr:link>'''</code></font> element MUST contain:<br />
<br />
* A required attribute called <font size="2"><code>'''href'''</code></font> whose value is a URL that when dereferenced will return the service response in the media type described by the value of the <font size="2"><code>'''type'''</code></font> attribute.<br />
* A required <font size="2"><code>'''type'''</code></font> attribute whose value is the media-type for the normative representation returned by that URL held in the <font size="2"><code>'''href'''</code></font> attribute.<br />
* An optional attribute called <font size="2"><code>'''description'''</code></font> whose value is a human readable string that provides a brief description of the <font size="2"><code>'''<dsr:link>'''</code></font> elements semantics.<br />
* Zero or more <font size="2"><code>'''<dsr:alt>'''</code></font> elements, one for each and every alternate representation of the response that can be requested using [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12.1 HTTP server-driven content negotiation] in conjunction with the <font size="2"><code>'''href'''</code></font> URL. Each <font size="2"><code>'''<dsr:alt>'''</code></font> element MUST contain:<br />
** A required <font size="2"><code>'''type'''</code></font> attribute whose value is the MIME type that would be used in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 HTTP '''Accept''' header] to request that representation from the server.<br />
<br />
==== Extensions Elements <font color="orange">(Place Holder: Needs Content!) </font> ====<br />
<br />
Details of the extensions (e.g. server side functions, etc.) should be inserted in this section.<br />
<br />
==== Example Response ====<br />
<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<?xml-stylesheet type="text/xsl" href="/opendap/xsl/serviceDescription.xsl"?><br />
<DatasetServices xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<br />
<DapVersion>4.0</DapVersion><br />
<DapVersion>3.2</DapVersion><br />
<DapVersion>2.0</DapVersion><br />
<br />
<ServerSoftwareVersion>Text or any XML element content as long as the XML is not in the document namespace</ServerSoftwareVersion><br />
<br />
<Description>This data resource description is optional and needs only to be human readable.</Description><br />
<br />
<Service title="DAP4 Dataset Services" role="http://services.opendap.org/dap4/dataset-services"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Services_Description_Service">An index of the Services available for this data resource.</Description><br />
<br />
<link description="Normative form of the DSR" <br />
type="application/vnd.opendap.org.dataset-services+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<alt type="text/html"/><br />
<alt type="text/xml"/><br />
</link><br />
<br />
<link description="HTML representation of the DSR" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html"/><br />
<br />
<link description="Normative DSR with generic Content-Type" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xml"/><br />
<br />
</Service><br />
<br />
<Service title="DAP4 Dataset Metadata" role="http://services.opendap.org/dap4/dataset-metadata"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Service_-_The_metadata">The DAP4 metadata content for this data resource..</Description><br />
<br />
<link description="Normative form of the DMR" <br />
type="application/vnd.org.opendap.dap4.dataset-metadata+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"><br />
<alt type="text/html"/><br />
<alt type="text/xml"/><br />
<alt type="application/rdf+xml"/><br />
</link><br />
<br />
<link description="Data Request Form" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.html"/><br />
<br />
<link description="Normative DMR with generic Content-Type" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.xml"/><br />
<br />
<link description="RDF representation of DMR" <br />
type="application/rdf+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rdf"/><br />
</Service><br />
<br />
<Service title="DAP4 Data" role="http://services.opendap.org/dap4/data"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Data_Service">DAP4 Data object for this data resource.</Description><br />
<link type="application/vnd.org.opendap.dap4.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap" ><br />
<alt type="text/plain"/><br />
<alt type="text/xml"/><br />
<alt type="application/x-netcdf"/><br />
</link><br />
<br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.ascii" /><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.xml" /><br />
<link type="application/x-netcdf" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.nc" /><br />
</Service><br />
<br />
<br />
<Service title="ISO-19115 Metadata Service" role="http://services.opendap.org/dap4/iso-19115"><br />
<link description="Dataset metadata as ISO-19115" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.iso"><br />
<link description="ISO-19115 score" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rubric"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO-19115 Metadata Representation of the DMR.</Description><br />
</Service><br />
<br />
<br />
<Service title="ISO-19115 Metadata Service" role="http://services.opendap.org/dap4/iso-19115"><br />
<link description="Dataset metadata as ISO-19115" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.iso"><br />
<alt type="text/html"/><br />
</link><br />
<link description="ISO-19115 conformance score" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rubric"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO-19115 conformance score for the DMR.</Description><br />
</Service><br />
<br />
<br />
<Service title="DAP2 Data" role="http://services.opendap.org/dap2/dods"><br />
<link type="application/octet-stream" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Data_Service">DAP2 Data Object.</Description><br />
</Service><br />
<br />
<Service title="DDX" role="http://services.opendap.org/dap2/ddx"><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDX_Service">OPeNDAP Data Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DDS" role="http://services.opendap.org/dap2/dds"><br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDS_Service">OPeNDAP Data Description Structure.</Description><br />
</Service><br />
<br />
<Service title="DAS" role="http://services.opendap.org/dap2/das" ><br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DAS_Service">OPeNDAP Dataset Attribute Structure.</Description><br />
</Service><br />
<br />
<br />
<Service title="INFO" role="http://services.opendap.org/dap2/info"><br />
<link type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Info_Service">OPeNDAP Dataset Information Page.</Description><br />
</Service><br />
<br />
<Service title="Server Version" role="http://services.opendap.org/dap4/version"><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Server_Version_Service">An XML document containing information about the software version of the server..</Description><br />
</Service><br />
<br />
<br />
<Service title="File Access" role="http://services.opendap.org/dap4/file"><br />
<link type="text/xml ## This value depends on the file being accessed." <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Native_File_Access_Service">Access to dataset file.</Description><br />
</Service><br />
<br />
<ServerSideFunction name="geogrid"<br />
role="http://services.opendap.org/dap4/server-side-function/geogrid"><br />
<Description href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid">Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="geogrid"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="grid"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using the values of the coordinate axes.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="linear_scale"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"><br />
<Description>Applies a linear scale transform to the named variable.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="version"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"><br />
<Description>Returns version information for each server side function.</Description><br />
</ServerSideFunction><br />
<extension name="async" role="http://opendap.org/extension/async"><br />
<Description href="">async</Description><br />
</extension><br />
<extension name="ferret" role="http://pmel.noaa.gov/dap4extension/ferret"<br />
type="serverSideProcessing"><br />
<Description href="">async</Description><br />
</extension><br />
</DatasetServices><br />
</source><br />
</font><br />
<br />
== Rationale for the solution ==<br />
<br />
The solution provides DAP4 servers with an interface that allows for both server-driven and agent driven content negotiation as described in [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html section 12 of the HTTP 1.1 specification]]. Providing the Dataset Services Response in XML allows many downstream applications to ingest the content and leaves open the option for server implementers to add XSLT references to the document so that clients like browsers can easily build a presentation view of the information. <!-- Using the Atom 1.0 appears to involve no additional overhead and will enable other uses for the response. --><br />
<br />
== Discussion ==<br />
<!-- It is possible to embed in the above a reference to a XSLT that will transform the above XML into HTML similar to the following (with the caveat that this image is actually of a similar, but not identical, XML response): --><br />
Here is one idea for the HTML version of the DSR; it could be generated by the server using XSLT on the XML or by the browser when the user explicitly requests the ''.xml'' variant of the response (by embedding a reference to the XSL transform in that response document):<br />
<br />
[[File:ServiceDescriptionPrototype-01.png]]<br />
<br />
<br />
<!--<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<?xml-stylesheet type="text/xsl" href="/opendap/xsl/serviceDescription.xsl"?><br />
<DatasetServices xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns:xlink="http://www.w3.org/1999/xlink" <br />
xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<br />
<Service title="DAP4 Dataset Services" xlink:role="http://services.opendap.org/dap4/dataset-services#"><br />
<link type="application/vnd.opendap.org.dataset-services+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xml"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Services_Description_Service">An XML document itemizing the Services available for this dataset.</Description><br />
</Service><br />
<br />
<br />
<Service title="DAP4 Dataset Metadata" xlink:role="http://services.opendap.org/dap4/dataset-metadata#"><br />
<link type="application/vnd.org.opendap.dap4.dataset-metadata+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"><br />
<link description="Data Request Form"<br />
type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.html"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.xml"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Service_-_The_metadata">DAP4 Dataset Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DAP4 Data" xlink:role="http://services.opendap.org/dap4/data#"><br />
<link type="application/vnd.org.opendap.dap4.data" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap" ><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.ascii" ><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.xml" ><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Data_Service">DAP4 Data object.</Description><br />
</Service><br />
<br />
<Service title="DAP2 Data" xlink:role="http://services.opendap.org/dap2/dods#"><br />
<link type="application/octet-stream" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Data_Service">DAP2 Data Object.</Description><br />
</Service><br />
<br />
<Service title="ASCII Data" xlink:role="http://services.opendap.org/dap4/ascii#"><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.asc"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ASCII_Data_Service">The DAP4 Data response in ASCII form.</Description><br />
</Service><br />
<br />
<Service title="NetCDF-File" xlink:role="http://services.opendap.org/dap4/netcdf-3#"><br />
<link type="application/x-netcdf" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.nc"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_NetCDF_File-out_Service">NetCDF file-out response.</Description><br />
</Service><br />
<br />
<Service title="XML Data Response" xlink:role="http://services.opendap.org/dap4/xml-data#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdap"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_XML_Data_Service">An XML document containing both the dataset's structural metadata along with data values.</Description><br />
</Service><br />
<br />
<Service title="DDX" xlink:role="http://services.opendap.org/dap2/ddx#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDX_Service">OPeNDAP Data Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DDS" xlink:role="http://services.opendap.org/dap2/dds#"><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDS_Service">OPeNDAP Data Description Structure.</Description><br />
</Service><br />
<br />
<Service title="DAS"<br />
xlink:role="http://services.opendap.org/dap2/das#" ><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DAS_Service">OPeNDAP Dataset Attribute Structure.</Description><br />
</Service><br />
<br />
<Service title="RDF" xlink:role="http://services.opendap.org/dap4/rdf#"><br />
<link type="application/rdf+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rdf"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_RDF_Service">An RDF representation of the Dataset response (DDX) document.</Description><br />
</Service><br />
<br />
<Service title="INFO" xlink:role="http://services.opendap.org/dap2/info#"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Info_Service">OPeNDAP Dataset Information Page.</Description><br />
</Service><br />
<br />
<Service title="Server Version" xlink:role="http://services.opendap.org/dap4/version#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Server_Version_Service">An XML document containing information about the software version of the server..</Description><br />
</Service><br />
<br />
<Service title="ISO-19115" xlink:role="http://services.opendap.org/dap4/iso-19115-metadata#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.iso"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_19115_Service">ISO 19115 Metadata Representation of the Dataset (DDX) response.</Description><br />
</Service><br />
<br />
<Service title="ISO-19115-Score" xlink:role="http://services.opendap.org/dap4/iso-19115-score#"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rubric"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO 19115 Metadata Representation conformance score for this dataset.</Description><br />
</Service><br />
<br />
<Service title="File Access" xlink:role="http://services.opendap.org/dap4/file#"><br />
<link type="text/xml ## This value depends on the file being accessed." <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Native_File_Access_Service">Access to dataset file.</Description><br />
</Service><br />
<br />
<ServerSideFunctions><br />
<Function name="geogrid"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</Function><br />
<Function name="grid"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using the values of the coordinate axes.</Description><br />
</Function><br />
<Function name="linear_scale"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"><br />
<Description>Applies a linear scale transform to the named variable.</Description><br />
</Function><br />
<Function name="version"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"><br />
<Description>Returns version information for each server side function.</Description><br />
</Function><br />
</ServerSideFunctions><br />
</DatasetServices><br />
</source><br />
</font><br />
--><br />
<br />
<br />
== Appendix: Dataset Services Response XML schema ==<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xs:schema <br />
targetNamespace="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns:xs="http://www.w3.org/2001/XMLSchema"<br />
xmlns:xml="http://www.w3.org/XML/1998/namespace"<br />
xmlns:dsr="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
elementFormDefault="qualified" <br />
attributeFormDefault="unqualified"><br />
<br />
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd"/><br />
<!--<br />
<br />
--><br />
<xs:element name="DatasetServices" type="DatasetServicesType"/><br />
<xs:element name="DapVersion" type="DapVersionType"/><br />
<xs:element name="SoftwareServerVersion" type="AnyXMLType"/><br />
<xs:element name="Service" type="ServiceType"/><br />
<xs:element name="Description" type="DescriptionType"/><br />
<xs:element name="link" type="linkType"/><br />
<xs:element name="alt" type="altType"/><br />
<!--<br />
<br />
--><br />
<xs:complexType name="DatasetServicesType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices root element type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="DapVersion" minOccurs="1" maxOccurs="unbounded"/><br />
<xs:element ref="SoftwareServerVersion" minOccurs="1" maxOccurs="1"/><br />
<xs:element ref="Description" minOccurs="0" maxOccurs="1"/><br />
<xs:element ref="Service" minOccurs="3" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute ref="xml:base" use="required"/><br />
<xs:attribute name="role" type="xs:anyURI" use="required"/><br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="ServiceType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices Service type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="Description" minOccurs="0" maxOccurs="1"/><br />
<xs:element ref="link" minOccurs="1" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute name="title" type="xs:string" use="optional"/><br />
<xs:attribute name="role" type="xs:anyURI" use="required"/><br />
</xs:complexType><br />
<!--<br />
<br />
--> <br />
<xs:simpleType name="DapVersionType"><br />
<xs:restriction base="xs:string"><br />
<xs:pattern value="\d{1,}.\d{1,}"></xs:pattern><br />
</xs:restriction><br />
</xs:simpleType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="DescriptionType"><br />
<xs:simpleContent><br />
<xs:extension base="xs:string"><br />
<xs:attribute name="href" type="xs:anyURI"/><br />
</xs:extension><br />
</xs:simpleContent><br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="altType"><br />
<xs:attribute name="type" type="xs:string"/><br />
</xs:complexType><br />
<!-- <br />
<br />
--><br />
<xs:complexType name="linkType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices link type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="alt" minOccurs="0" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute name="href" type="xs:string" use="required"/><br />
<xs:attribute name="type" type="xs:string" use="required"/><br />
<xs:attribute name="description" type="xs:string" use="optional"/> <br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="AnyXMLType"><br />
<xs:annotation><br />
<xs:documentation><br />
Use this to embed arbitrary XML in an element. The resulting elements <br />
contents are ignored by DAP software. Other software<br />
might find the information useful. The XML elements must<br />
satisfy the requirements for 'lax' processing under schema 1.0.<br />
In practice, that means just about anything.<br />
<br />
name: A name to associate with this chunk of XML<br />
*: This element can contain any other attributes that conform <br />
to the schema 1.0 definition of 'lax' processing<br />
<br />
( <xs:any/>+ ) <br />
</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:any namespace="##any" minOccurs="0" processContents="lax"/><br />
</xs:sequence><br />
<xs:anyAttribute processContents="lax" namespace="##any"/><br />
</xs:complexType><br />
<br />
<br />
</xs:schema><br />
<br />
</source><br />
</font><br />
<br />
== fini ==<br />
<br />
Contains cruft in comments...<br />
<br />
<br />
<!--<br />
I also put together a simple XSLT to make this a human friendly HTML. I added a reference to it in the XML document. When you point a browser at the resource URL (For example http://localhost:8080/opendap/data/nc/fnoc1.nc ) the Service Description response is returned as an XML file (above), the browser detects the xml-stylesheet reference, grabs the XSLT, uses it to convert the XML to HTML and renders it like this:<br />
<br />
[[File:ServiceDescriptionPrototype-01.png]]<br />
<br />
== Rationale for the solution ==<br />
<br />
The solution provides DAP4 servers with an interface that allows for both server-driven and agent driven content negotiation as described in [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html section 12 of the HTTP 1.1 specification]]. Providing the DatasetServices response in XML allows many downstream applications to ingest the content and leaves open the option for server implementers to add XSLT references to the document so that clients like browsers can easily build a presentation view of the information.<br />
<br />
== Discussion ==<br />
<br />
<br />
=== Using Atom 1.0 ===<br />
<br />
The proposed encoding for this information is to use [http://en.wikipedia.org/wiki/Atom_(standard) Atom 1.0]. The advantages of this encoding are several and the detractions are close to nil. Atom 1.0 provides the DAP with a widely-used standard for representing information that is very general in nature (that data are accessible using a set of web services, each of which provides a sightly different kind of response and can be accessed using a different URL). Furthermore, we can use this same response in other responses a server might like to provide such as a ''data cast'' provides to subscribers or an OpenSearch result. Using Atom is important in those contexts because a response that it not specific to DAP is a requirement. At the same time, because the Atom specification does not impose needless or complex additional requirements, the cost of using it is low. In fact the only information in Atom 1.0 that is not listed above is a the name and email of an ''author'' for the ''entry''. While this might be rationalization, including that information could help a number of users who send email to support lists asking about dataset ''X'' simply because they don't know where/who else to ask.<br />
<br />
Using Atom, A DAP4 web service is described by:<br />
* An 'entry' that serves to group a set of ''link'' elements that reference different services to a common set of information about the dataset. For the dataset, that information is:<br />
** A simple human readable name called ''title''.<br />
** An ''id'' that uniquely identifies the ''entry''.<br />
** The last modified time for the dataset (''updated'').<br />
** A person responsible for the dataset (''author'').<br />
** An optional ''content'' element. (well, it's conditionally optional - see the [http://tools.ietf.org/html/rfc4287 Atom spec])<br />
* For each service, a ''link'' element is used where the four attributes ''title'', '' rel'', ''type'', ''href'' are used as follows:<br />
** ''title'' - A human-readable description of the service<br />
** ''rel'' - See the [http://tools.ietf.org/html/rfc4287 Atom spec]<br />
** ''type'' - A MIME-type that identifies the response as specific to OPeNDAP such as ''application/vnd.opendap.org.dap4.xdp+xml''<br />
** ''href'' - The full URL used to get the response<br />
<br />
For the Atom-based response, we propose to use MIME types as Ethan suggested (application/vnd.opendap.org.dap4.data etc.) when describing services in the Dataset Services Response, and then, when the server provides those responses over HTTP it sets the content header to the [[DAP4_Web_Services_v3#Media_Types | lowest common mime type]]. <br />
<br />
For example, in the Dataset Services response we might describe the Dataset Metadata service like this:<br />
<font size="2"><br />
<source lang="xml" ><br />
...<br />
<link title="DAP4 Dataset Metadata XML Document."<br />
rel="related"<br />
type="application/vnd.opendap.org.dap4.xdp+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp"/><br />
...<br />
</source><br />
</font><br />
<br />
And when a DAP4 server responds to a client asking for http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp the server would set the HTTP headers so that the Content-Type would be the [[DAP4_Web_Services_v3#Media_Types | lowest common mime type]] (in this case ''text/xml'') . The server could put the more expressive type tag in the ''Content-Description'' header:<br />
<font size="2"><br />
<source lang="txt" ><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: test/xml<br />
Content-Description: application/vnd.opendap.org.dap4.xdp+xml; url=http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp<br />
Content-Encoding: gzip<br />
X-DAP: 4.0<br />
</source><br />
</font><br />
<br />
For normative information on Atom, see [http://tools.ietf.org/html/rfc5023 RFC 5023] and [http://tools.ietf.org/html/rfc4287 RFC 4287].<br />
<br />
==== Example: Validated Atom Document with one atom:entry for a dataset, and an atom:link for each service ====<br />
<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<entry xmlns="http://www.w3.org/2005/Atom"><br />
<br />
<title>DatasetServices: ECMWF_ERA-40_subset.ncml</title><br />
<br />
<id>http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml</id><br />
<br />
<updated>2003-12-13T18:30:02-05:00</updated><br />
<br />
<author><br />
<name>Nathan Potter</name><br />
<email>johndoe@devnull.com</email><br />
</author><br />
<content type="xhtml" xml:lang="en" xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<div xmlns="http://www.w3.org/1999/xhtml">DAP Dataset Services for http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml</div><br />
</content><br />
<br />
<link title="Dataset Services Description"<br />
rel="self"<br />
type="application/atom+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"/><br />
<br />
<link title="DAP4 Dataset Metadata XML Document."<br />
rel="related"<br />
type="application/vnd.opendap.org.dap4.dmr+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"/><br />
<br />
<link title="DAP4 Data object."<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap4.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap"/><br />
<br />
<link title="OPeNDAP HTML Data Request Form for data sub-setting and access."<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html" /><br />
<br />
<link title="DAP2 Data Object."<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap2.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"/><br />
<br />
<link title="DAP4 Data response in ASCII form."<br />
rel="enclosure"<br />
type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.asc"/><br />
<br />
<link title="NetCDF-3 file-out response."<br />
rel="enclosure"<br />
type="application/x-netcdf" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.nc"/><br />
<br />
<link title="XML Data Response"<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap4.data+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdap"/><br />
<br />
<link title="DAP2 DDX document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.ddx+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"/><br />
<br />
<link title="DAP2 DDS document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.dds" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"/><br />
<br />
<link title="DAP2 DAS document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.dds" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"/><br />
<br />
<link title="RDF representation of the Dataset Metadata response."<br />
rel="related"<br />
type="application/rdf+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rdf"/><br />
<br />
<link title="DAP2 Dataset Information Page"<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"/><br />
<br />
<link title="Server Version Document"<br />
rel="related"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"/><br />
<br />
<link title="ISO 19115 Metadata Representation of the Dataset (DDX) response."<br />
rel="related"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.iso"/><br />
<br />
<link title="ISO 19115 Metadata Representation conformance score for this dataset."<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rubric"/><br />
<br />
<link title="Dataset file access"<br />
rel="enclosure"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"/><br />
<br />
</entry><br />
<br />
<br />
</source><br />
</font><br />
--></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Dataset_Services_Response&diff=9311DAP4 Dataset Services Response2012-09-05T22:18:14Z<p>EthanDavis: /* Example Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
<br />
[[OPULS_Development | <-- back to OPULS Development]]<br />
<br />
Author: [[User:Ndp|ndp]]<br />
<br />
== Background ==<br />
<br />
DAP2, while successful within several arenas in the scientific community, failed to provide a complete description of the web interface that a server should support. This came about for two reasons: DAP2 was developed at a time when 'web services' was an idea in considerable flux and, secondly, the DAP2 specification was written to focus on a data model (mostly) that supported interoperability. The current DAP4 draft specification document, like the DAP2 specification, does not address how a web-based interface to DAP4 should be built. However, we are going to provide a specification that will describe how such an interface for DAP4 should be built and this document contains information that should be part of that specification.<br />
<br />
== Problem addressed ==<br />
<br />
Currently DAP2 servers provide a number of dataset level responses (services). These include DAP2 services such as the DDS, DAS, and DDX, plus other services that have been added over time such as the RDF and ISO responses. There is currently no way for a user (or software agent) to discover which of these many services might be available for a particular dataset. While THREDDS catalogs do provide a mechanism for determining which services are associated with which datasets, they don't actually provide a mechanism for discovering the details of the various service URLs. A THREDDS catalog might identify a DAP2 service, but the URL that can be assembled from the THREDDS catalog for that service is limited to just the base dataset URL. Typically dereferencing this URL will provide one of two things - either the underlying data file (for example a netcdf file) or an HTTP 403 error if direct access to the underlying files has been disabled in the server configuration.<br />
<br />
'''Example:'''<br />
<br />
This URL points to a dataset on a DAP2 server:<br />
<font size="2"><br />
http://test.opendap.org:8080/opendap/data/nc/fnoc1.nc<br />
</font><br />
<br />
Dereferencing the link will not connect you to a DAP2 service or DAP2 response. It will (likely) return the underlying netcdf file. The only way to know that DAP2 services exist for this is by reading the URL path and recognizing that it is probably an instance of a DAP2 server based on the composition of the URL. In fact, there is no guarantee that dereferencing this URL will even yield the underlying file, as that behavior is a configuration option for some server implementations. If that access is not allowed in the configuration, then dereferencing the URL will simply return an HTTP 403 (forbidden) error.<br />
<br />
== Proposed solution ==<br />
<br />
We intend to provide a 'Services' or 'Capabilities' response for DAP4. Dereferencing an unadorned DAP4 dataset resource URL will return a document describing the DAP services available for the dataset. This will be a required response and the only valid response for an 'unadorned' dataset resource URL. We will refer to this response as the 'Dataset Services Response' or 'DSR' in the 'DAP4 Web Services' specification and the remainder of this document. <br />
<br />
At minimum this document MUST provide, for each service available for the dataset:<br />
<br />
* A human readable title of that service (e.g., The DDX service for the dataset)<br />
* One or more links that can be dereferenced to get the various representations of the response for the dataset.<br />
* An unambiguous, unique to the service type, resource role ID that serves as a way to clearly identify what each service does.<br />
* A brief description of the service<br />
<br />
The response should also include:<br />
* A link to a complete, human readable, description of the service.<br />
* A reference to an XSLT that a browser would use to render the description into HTML for a presentation view.<br />
* Descriptions and syntax of server side functions available for the dataset<br />
<br />
=== Service Access ===<br />
<br />
A service is accessed by dereferencing one of the access URLs held in the <font size="2"><code>'''href'''</code></font> attribute of a <font size="2"><code>'''<dsr:link>'''</code></font> elements, 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.<br />
<br />
A more extensive discussion of the various services that might appear in a DatasetServices document can be found on the [[DAP4 Web Services v3]] page.<br />
<br />
'''Note:''' If a client understands how to modify/augment the dataset resource URL ( as described in the [[DAP4_Web_Services_v3#Web_Services | DAP4 Web Services Specification]] ) such that it becomes a DAP response URL then it need never obtain the Dataset Services response.<br />
<br />
=== Dataset Services Response Encoding === <br />
<br />
c.f. [[DAP4_Web_Services v3| DAP4 Web Services]]<br />
<br />
''In this section the namespace prefix <font size="2"><code>'''dsr'''</code></font> is associated with the namespace '''<font size="2"><code><nowiki>http://xml.opendap.org/ns/DAP/4.0/dataset-services#</nowiki></code></font>'''.''<br />
<br />
==== dsr:DatasetServices Element ====<br />
<br />
The Dataset Services Response MUST contain a top level <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element. This <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element MUST contain:<br />
* An <font size="2"><code>'''xml:base'''</code></font> attribute whose value is the resource URL that was dereferenced to request the DSR response.<br />
* A list of DAP versions supported by server<br />
*: These appear as one or more child <font size="2"><code>'''<dsr:DapVersion>'''</code></font> elements of the <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element.<br />
* The implementation version of the server that produced the DSR.<br />
*: This appears as a single <font size="2"><code>'''<dsr:ServerSoftwareVersion>'''</code></font> child element of the <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element. <br />
* A list of all available DAP4 services for the dataset<br />
*: This is represented as 3 or more <font size="2"><code>'''[[#Service_Element | <dsr:Service>]]'''</code></font> elements. (There are 3 required services for a DAP4 server.) <br />
* A list of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
The <font size="2"><code>'''<dsr:DatasetServices>'''</code></font> element SHOULD contain:<br />
* A <font size="2"><code>'''title'''</code></font> attribute whose value is a human readable title for the dataset.<br />
<br />
==== dsr:DapVersion Element ====<br />
The <font size="2"><code>'''<dsr:DapVersion>'''</code></font> element contains a single DAP version value as a text string. The DAP version is represented as two integer values separated by a period, MM.mm where the first value (MM) is the major version of the DAP protocol, and the second value (mm) is the minor version. Multiple <font size="2"><code>'''<dsr:DapVersion>'''</code></font> elements are used to represent that server can support multiple versions of the DAP protocol, one instance for each supported version.<br />
<br />
Example:<br />
<font size="2"><br />
<source lang="xml" ><br />
<DapVersion>4.0</DapVersion><br />
<DapVersion>3.2</DapVersion><br />
<DapVersion>2.0</DapVersion><br />
</source><br />
</font><br />
<br />
==== dsr:ServerSoftwareVersion Element ====<br />
<br />
The <font size="2"><code>'''<dsr:ServerSoftwareVersion>'''</code></font> element has no attributes and may contain as little as a simple text string (e.g., "TDS 4.3.57" or "Hyrax 1.7.45"), or it may contain any well-formed XML content not in the <font size="2"><code>'''dsr'''</code></font> namespace that the server implementer sees fit to use to describe the software version of their server implementation.<br />
<br />
==== dsr:Service Element ====<br />
<br />
Each DAP4 web service is described by a <font size="2"><code>'''<dsr:Service>'''</code></font> element with:<br />
* An optional <font size="2"><code>'''title'''</code></font> attribute whose value is a simple human readable title for the service. <br />
* An required <font size="2"><code>'''role'''</code></font> attribute whose value is a unique to the service type, resource role ID (a URI) that serves as a way to clearly identify what each service does. This is intended to allow people and software to unambiguously identify specific services, irrespective of their human readable title. The idea is that that the role attribute tells you what is going to happen when you dereference the URL held in the <font size="2"><code>'''<dsr:link>'''</code></font> element. Each service has a single role and all of the links (alternate representations) must fulfill the same role.<br />
* An optional <font size="2"><code>'''<dsr:Description>'''</code></font> element .<br />
* One or more <font size="2"><code>'''<dsr:link>'''</code></font> elements.<br />
<br />
===== Regarding the <font size="3"><code>'''role'''</code></font> attribute =====<br />
<br />
With regards to multiple representations of a service response and the <font size="2"><code>'''role'''</code></font> attribute: While there may be many alternate representations of a response, not all will fufill the same <font size="2"><code>'''role'''</code></font>. Representations fulfilling the same <font size="2"><code>'''role'''</code></font> should be bundled together in their own '''Service''' with the appropriate <font size="2"><code>'''role'''</code></font> value. For example the DMR can be mapped to the ISO19115 metadata space, but IS0-19115 responses are clearly outside of the <font size="2"><code>'''role'''</code></font> of the regular DMR service, which returns a DAP4 metadata response. One could view it as the two roles described different domains.<br />
<br />
==== dsr:Description Element ====<br />
Each <font size="2"><code>'''<dsr:Description>'''</code></font> element MUST contain:<br />
* An optional <font size="2"><code>'''href'''</code></font> attribute whose value is a URL string that points to a human readable document describing the service. <br />
* The required text content of the <font size="2"><code>'''dsr:Description'''</code></font> element MUST be a human readable description of the service.<br />
<br />
==== dsr:link Element ====<br />
<br />
Each <font size="2"><code>'''<dsr:link>'''</code></font> element MUST contain:<br />
<br />
* A required attribute called <font size="2"><code>'''href'''</code></font> whose value is a URL that when dereferenced will return the service response in the media type described by the value of the <font size="2"><code>'''type'''</code></font> attribute.<br />
* A required <font size="2"><code>'''type'''</code></font> attribute whose value is the media-type for the normative representation returned by that URL held in the <font size="2"><code>'''href'''</code></font> attribute.<br />
* An optional attribute called <font size="2"><code>'''description'''</code></font> whose value is a human readable string that provides a brief description of the <font size="2"><code>'''<dsr:link>'''</code></font> elements semantics.<br />
* Zero or more <font size="2"><code>'''<dsr:alt>'''</code></font> elements, one for each and every alternate representation of the response that can be requested using [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12.1 HTTP server-driven content negotiation] in conjunction with the <font size="2"><code>'''href'''</code></font> URL. Each <font size="2"><code>'''<dsr:alt>'''</code></font> element MUST contain:<br />
** A required <font size="2"><code>'''type'''</code></font> attribute whose value is the MIME type that would be used in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 HTTP '''Accept''' header] to request that representation from the server.<br />
<br />
==== Extensions Elements <font color="orange">(Place Holder: Needs Content!) </font> ====<br />
<br />
Details of the extensions (e.g. server side functions, etc.) should be inserted in this section.<br />
<br />
==== Example Response ====<br />
<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<?xml-stylesheet type="text/xsl" href="/opendap/xsl/serviceDescription.xsl"?><br />
<DatasetServices xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<br />
<DapVersion>4.0</DapVersion><br />
<DapVersion>3.2</DapVersion><br />
<DapVersion>2.0</DapVersion><br />
<br />
<ServerSoftwareVersion>Text or any XML element content as long as the XML is not in the document namespace</ServerSoftwareVersion><br />
<br />
<Description>This data resource description is optional and needs only to be human readable.</Description><br />
<br />
<Service title="DAP4 Dataset Services" role="http://services.opendap.org/dap4/dataset-services"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Services_Description_Service">An index of the Services available for this data resource.</Description><br />
<br />
<link description="Normative form of the DSR" <br />
type="application/vnd.opendap.org.dataset-services+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<alt type="text/html"/><br />
<alt type="text/xml"/><br />
</link><br />
<br />
<link description="HTML representation of the DSR" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html"/><br />
<br />
<link description="Normative DSR with generic Content-Type" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xml"/><br />
<br />
</Service><br />
<br />
<Service title="DAP4 Dataset Metadata" role="http://services.opendap.org/dap4/dataset-metadata"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Service_-_The_metadata">The DAP4 metadata content for this data resource..</Description><br />
<br />
<link description="Normative form of the DMR" <br />
type="application/vnd.org.opendap.dap4.dataset-metadata+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"><br />
<alt type="text/html"/><br />
<alt type="text/xml"/><br />
<alt type="application/rdf+xml"/><br />
</link><br />
<br />
<link description="Data Request Form" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.html"/><br />
<br />
<link description="Normative DMR with generic Content-Type" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.xml"/><br />
<br />
<link description="RDF representation of DMR" <br />
type="application/rdf+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rdf"/><br />
</Service><br />
<br />
<Service title="DAP4 Data" role="http://services.opendap.org/dap4/data"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Data_Service">DAP4 Data object for this data resource.</Description><br />
<link type="application/vnd.org.opendap.dap4.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap" ><br />
<alt type="text/plain"/><br />
<alt type="text/xml"/><br />
<alt type="application/x-netcdf"/><br />
</link><br />
<br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.ascii" /><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.xml" /><br />
<link type="application/x-netcdf" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.nc" /><br />
</Service><br />
<br />
<br />
<Service title="ISO-19115 Metadata Service" role="http://services.opendap.org/dap4/iso-19115"><br />
<link description="Dataset metadata as ISO-19115" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.iso"><br />
<link description="ISO-19115 score" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rubric"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO-19115 Metadata Representation of the DMR.</Description><br />
</Service><br />
<br />
<br />
<Service title="ISO-19115 Metadata Service" role="http://services.opendap.org/dap4/iso-19115"><br />
<link description="Dataset metadata as ISO-19115" <br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.iso"><br />
<alt type="text/html"/><br />
</link><br />
<link description="ISO-19115 conformance score" <br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.rubric"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO-19115 conformance score for the DMR.</Description><br />
</Service><br />
<br />
<br />
<Service title="DAP2 Data" role="http://services.opendap.org/dap2/dods"><br />
<link type="application/octet-stream" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Data_Service">DAP2 Data Object.</Description><br />
</Service><br />
<br />
<Service title="DDX" role="http://services.opendap.org/dap2/ddx"><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDX_Service">OPeNDAP Data Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DDS" role="http://services.opendap.org/dap2/dds"><br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDS_Service">OPeNDAP Data Description Structure.</Description><br />
</Service><br />
<br />
<Service title="DAS" role="http://services.opendap.org/dap2/das" ><br />
<link type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DAS_Service">OPeNDAP Dataset Attribute Structure.</Description><br />
</Service><br />
<br />
<br />
<Service title="INFO" role="http://services.opendap.org/dap2/info"><br />
<link type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Info_Service">OPeNDAP Dataset Information Page.</Description><br />
</Service><br />
<br />
<Service title="Server Version" role="http://services.opendap.org/dap4/version"><br />
<link type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Server_Version_Service">An XML document containing information about the software version of the server..</Description><br />
</Service><br />
<br />
<br />
<Service title="File Access" role="http://services.opendap.org/dap4/file"><br />
<link type="text/xml ## This value depends on the file being accessed." <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"><br />
<Description href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Native_File_Access_Service">Access to dataset file.</Description><br />
</Service><br />
<br />
<ServerSideFunction name="geogrid"<br />
role="http://services.opendap.org/dap4/server-side-function/geogrid"><br />
<Description href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid">Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="geogrid"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="grid"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using the values of the coordinate axes.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="linear_scale"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"><br />
<Description>Applies a linear scale transform to the named variable.</Description><br />
</ServerSideFunction><br />
<ServerSideFunction name="version"<br />
href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"><br />
<Description>Returns version information for each server side function.</Description><br />
</ServerSideFunction><br />
<extension name="async" role="http://opendap.org/extension/async"><br />
<Description href="">async</Description><br />
</extension><br />
</DatasetServices><br />
</source><br />
</font><br />
<br />
== Rationale for the solution ==<br />
<br />
The solution provides DAP4 servers with an interface that allows for both server-driven and agent driven content negotiation as described in [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html section 12 of the HTTP 1.1 specification]]. Providing the Dataset Services Response in XML allows many downstream applications to ingest the content and leaves open the option for server implementers to add XSLT references to the document so that clients like browsers can easily build a presentation view of the information. <!-- Using the Atom 1.0 appears to involve no additional overhead and will enable other uses for the response. --><br />
<br />
== Discussion ==<br />
<!-- It is possible to embed in the above a reference to a XSLT that will transform the above XML into HTML similar to the following (with the caveat that this image is actually of a similar, but not identical, XML response): --><br />
Here is one idea for the HTML version of the DSR; it could be generated by the server using XSLT on the XML or by the browser when the user explicitly requests the ''.xml'' variant of the response (by embedding a reference to the XSL transform in that response document):<br />
<br />
[[File:ServiceDescriptionPrototype-01.png]]<br />
<br />
<br />
<!--<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<?xml-stylesheet type="text/xsl" href="/opendap/xsl/serviceDescription.xsl"?><br />
<DatasetServices xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns:xlink="http://www.w3.org/1999/xlink" <br />
xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<br />
<Service title="DAP4 Dataset Services" xlink:role="http://services.opendap.org/dap4/dataset-services#"><br />
<link type="application/vnd.opendap.org.dataset-services+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xml"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Services_Description_Service">An XML document itemizing the Services available for this dataset.</Description><br />
</Service><br />
<br />
<br />
<Service title="DAP4 Dataset Metadata" xlink:role="http://services.opendap.org/dap4/dataset-metadata#"><br />
<link type="application/vnd.org.opendap.dap4.dataset-metadata+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"><br />
<link description="Data Request Form"<br />
type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.html"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr.xml"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Dataset_Service_-_The_metadata">DAP4 Dataset Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DAP4 Data" xlink:role="http://services.opendap.org/dap4/data#"><br />
<link type="application/vnd.org.opendap.dap4.data" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap" ><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.ascii" ><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap.xml" ><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Data_Service">DAP4 Data object.</Description><br />
</Service><br />
<br />
<Service title="DAP2 Data" xlink:role="http://services.opendap.org/dap2/dods#"><br />
<link type="application/octet-stream" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Data_Service">DAP2 Data Object.</Description><br />
</Service><br />
<br />
<Service title="ASCII Data" xlink:role="http://services.opendap.org/dap4/ascii#"><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.asc"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ASCII_Data_Service">The DAP4 Data response in ASCII form.</Description><br />
</Service><br />
<br />
<Service title="NetCDF-File" xlink:role="http://services.opendap.org/dap4/netcdf-3#"><br />
<link type="application/x-netcdf" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.nc"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_NetCDF_File-out_Service">NetCDF file-out response.</Description><br />
</Service><br />
<br />
<Service title="XML Data Response" xlink:role="http://services.opendap.org/dap4/xml-data#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdap"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_XML_Data_Service">An XML document containing both the dataset's structural metadata along with data values.</Description><br />
</Service><br />
<br />
<Service title="DDX" xlink:role="http://services.opendap.org/dap2/ddx#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDX_Service">OPeNDAP Data Description and Attribute XML Document.</Description><br />
</Service><br />
<br />
<Service title="DDS" xlink:role="http://services.opendap.org/dap2/dds#"><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DDS_Service">OPeNDAP Data Description Structure.</Description><br />
</Service><br />
<br />
<Service title="DAS"<br />
xlink:role="http://services.opendap.org/dap2/das#" ><br />
<link type="text/plain" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_DAS_Service">OPeNDAP Dataset Attribute Structure.</Description><br />
</Service><br />
<br />
<Service title="RDF" xlink:role="http://services.opendap.org/dap4/rdf#"><br />
<link type="application/rdf+xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rdf"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_RDF_Service">An RDF representation of the Dataset response (DDX) document.</Description><br />
</Service><br />
<br />
<Service title="INFO" xlink:role="http://services.opendap.org/dap2/info#"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP2:_Info_Service">OPeNDAP Dataset Information Page.</Description><br />
</Service><br />
<br />
<Service title="Server Version" xlink:role="http://services.opendap.org/dap4/version#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Server_Version_Service">An XML document containing information about the software version of the server..</Description><br />
</Service><br />
<br />
<Service title="ISO-19115" xlink:role="http://services.opendap.org/dap4/iso-19115-metadata#"><br />
<link type="text/xml" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.iso"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_19115_Service">ISO 19115 Metadata Representation of the Dataset (DDX) response.</Description><br />
</Service><br />
<br />
<Service title="ISO-19115-Score" xlink:role="http://services.opendap.org/dap4/iso-19115-score#"><br />
<link type="text/html" <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rubric"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_ISO_Conformance_Score_Service">ISO 19115 Metadata Representation conformance score for this dataset.</Description><br />
</Service><br />
<br />
<Service title="File Access" xlink:role="http://services.opendap.org/dap4/file#"><br />
<link type="text/xml ## This value depends on the file being accessed." <br />
xlink:href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"><br />
<Description xlink:href="http://docs.opendap.org/index.php/DAP4_Web_Services#DAP4:_Native_File_Access_Service">Access to dataset file.</Description><br />
</Service><br />
<br />
<ServerSideFunctions><br />
<Function name="geogrid"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using georeferenced values.</Description><br />
</Function><br />
<Function name="grid"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"><br />
<Description>Allows a DAP Grid variable to be sub-sampled using the values of the coordinate axes.</Description><br />
</Function><br />
<Function name="linear_scale"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"><br />
<Description>Applies a linear scale transform to the named variable.</Description><br />
</Function><br />
<Function name="version"<br />
xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"><br />
<Description>Returns version information for each server side function.</Description><br />
</Function><br />
</ServerSideFunctions><br />
</DatasetServices><br />
</source><br />
</font><br />
--><br />
<br />
<br />
== Appendix: Dataset Services Response XML schema ==<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<xs:schema <br />
targetNamespace="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns:xs="http://www.w3.org/2001/XMLSchema"<br />
xmlns:xml="http://www.w3.org/XML/1998/namespace"<br />
xmlns:dsr="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
xmlns="http://xml.opendap.org/ns/DAP/4.0/dataset-services#"<br />
elementFormDefault="qualified" <br />
attributeFormDefault="unqualified"><br />
<br />
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd"/><br />
<!--<br />
<br />
--><br />
<xs:element name="DatasetServices" type="DatasetServicesType"/><br />
<xs:element name="DapVersion" type="DapVersionType"/><br />
<xs:element name="SoftwareServerVersion" type="AnyXMLType"/><br />
<xs:element name="Service" type="ServiceType"/><br />
<xs:element name="Description" type="DescriptionType"/><br />
<xs:element name="link" type="linkType"/><br />
<xs:element name="alt" type="altType"/><br />
<!--<br />
<br />
--><br />
<xs:complexType name="DatasetServicesType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices root element type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="DapVersion" minOccurs="1" maxOccurs="unbounded"/><br />
<xs:element ref="SoftwareServerVersion" minOccurs="1" maxOccurs="1"/><br />
<xs:element ref="Description" minOccurs="0" maxOccurs="1"/><br />
<xs:element ref="Service" minOccurs="3" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute ref="xml:base" use="required"/><br />
<xs:attribute name="role" type="xs:anyURI" use="required"/><br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="ServiceType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices Service type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="Description" minOccurs="0" maxOccurs="1"/><br />
<xs:element ref="link" minOccurs="1" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute name="title" type="xs:string" use="optional"/><br />
<xs:attribute name="role" type="xs:anyURI" use="required"/><br />
</xs:complexType><br />
<!--<br />
<br />
--> <br />
<xs:simpleType name="DapVersionType"><br />
<xs:restriction base="xs:string"><br />
<xs:pattern value="\d{1,}.\d{1,}"></xs:pattern><br />
</xs:restriction><br />
</xs:simpleType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="DescriptionType"><br />
<xs:simpleContent><br />
<xs:extension base="xs:string"><br />
<xs:attribute name="href" type="xs:anyURI"/><br />
</xs:extension><br />
</xs:simpleContent><br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="altType"><br />
<xs:attribute name="type" type="xs:string"/><br />
</xs:complexType><br />
<!-- <br />
<br />
--><br />
<xs:complexType name="linkType"> <br />
<xs:annotation><br />
<xs:documentation>DatasetServices link type</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:element ref="alt" minOccurs="0" maxOccurs="unbounded"/><br />
</xs:sequence><br />
<xs:attribute name="href" type="xs:string" use="required"/><br />
<xs:attribute name="type" type="xs:string" use="required"/><br />
<xs:attribute name="description" type="xs:string" use="optional"/> <br />
</xs:complexType><br />
<!--<br />
<br />
--><br />
<xs:complexType name="AnyXMLType"><br />
<xs:annotation><br />
<xs:documentation><br />
Use this to embed arbitrary XML in an element. The resulting elements <br />
contents are ignored by DAP software. Other software<br />
might find the information useful. The XML elements must<br />
satisfy the requirements for 'lax' processing under schema 1.0.<br />
In practice, that means just about anything.<br />
<br />
name: A name to associate with this chunk of XML<br />
*: This element can contain any other attributes that conform <br />
to the schema 1.0 definition of 'lax' processing<br />
<br />
( <xs:any/>+ ) <br />
</xs:documentation><br />
</xs:annotation><br />
<xs:sequence><br />
<xs:any namespace="##any" minOccurs="0" processContents="lax"/><br />
</xs:sequence><br />
<xs:anyAttribute processContents="lax" namespace="##any"/><br />
</xs:complexType><br />
<br />
<br />
</xs:schema><br />
<br />
</source><br />
</font><br />
<br />
== fini ==<br />
<br />
Contains cruft in comments...<br />
<br />
<br />
<!--<br />
I also put together a simple XSLT to make this a human friendly HTML. I added a reference to it in the XML document. When you point a browser at the resource URL (For example http://localhost:8080/opendap/data/nc/fnoc1.nc ) the Service Description response is returned as an XML file (above), the browser detects the xml-stylesheet reference, grabs the XSLT, uses it to convert the XML to HTML and renders it like this:<br />
<br />
[[File:ServiceDescriptionPrototype-01.png]]<br />
<br />
== Rationale for the solution ==<br />
<br />
The solution provides DAP4 servers with an interface that allows for both server-driven and agent driven content negotiation as described in [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html section 12 of the HTTP 1.1 specification]]. Providing the DatasetServices response in XML allows many downstream applications to ingest the content and leaves open the option for server implementers to add XSLT references to the document so that clients like browsers can easily build a presentation view of the information.<br />
<br />
== Discussion ==<br />
<br />
<br />
=== Using Atom 1.0 ===<br />
<br />
The proposed encoding for this information is to use [http://en.wikipedia.org/wiki/Atom_(standard) Atom 1.0]. The advantages of this encoding are several and the detractions are close to nil. Atom 1.0 provides the DAP with a widely-used standard for representing information that is very general in nature (that data are accessible using a set of web services, each of which provides a sightly different kind of response and can be accessed using a different URL). Furthermore, we can use this same response in other responses a server might like to provide such as a ''data cast'' provides to subscribers or an OpenSearch result. Using Atom is important in those contexts because a response that it not specific to DAP is a requirement. At the same time, because the Atom specification does not impose needless or complex additional requirements, the cost of using it is low. In fact the only information in Atom 1.0 that is not listed above is a the name and email of an ''author'' for the ''entry''. While this might be rationalization, including that information could help a number of users who send email to support lists asking about dataset ''X'' simply because they don't know where/who else to ask.<br />
<br />
Using Atom, A DAP4 web service is described by:<br />
* An 'entry' that serves to group a set of ''link'' elements that reference different services to a common set of information about the dataset. For the dataset, that information is:<br />
** A simple human readable name called ''title''.<br />
** An ''id'' that uniquely identifies the ''entry''.<br />
** The last modified time for the dataset (''updated'').<br />
** A person responsible for the dataset (''author'').<br />
** An optional ''content'' element. (well, it's conditionally optional - see the [http://tools.ietf.org/html/rfc4287 Atom spec])<br />
* For each service, a ''link'' element is used where the four attributes ''title'', '' rel'', ''type'', ''href'' are used as follows:<br />
** ''title'' - A human-readable description of the service<br />
** ''rel'' - See the [http://tools.ietf.org/html/rfc4287 Atom spec]<br />
** ''type'' - A MIME-type that identifies the response as specific to OPeNDAP such as ''application/vnd.opendap.org.dap4.xdp+xml''<br />
** ''href'' - The full URL used to get the response<br />
<br />
For the Atom-based response, we propose to use MIME types as Ethan suggested (application/vnd.opendap.org.dap4.data etc.) when describing services in the Dataset Services Response, and then, when the server provides those responses over HTTP it sets the content header to the [[DAP4_Web_Services_v3#Media_Types | lowest common mime type]]. <br />
<br />
For example, in the Dataset Services response we might describe the Dataset Metadata service like this:<br />
<font size="2"><br />
<source lang="xml" ><br />
...<br />
<link title="DAP4 Dataset Metadata XML Document."<br />
rel="related"<br />
type="application/vnd.opendap.org.dap4.xdp+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp"/><br />
...<br />
</source><br />
</font><br />
<br />
And when a DAP4 server responds to a client asking for http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp the server would set the HTTP headers so that the Content-Type would be the [[DAP4_Web_Services_v3#Media_Types | lowest common mime type]] (in this case ''text/xml'') . The server could put the more expressive type tag in the ''Content-Description'' header:<br />
<font size="2"><br />
<source lang="txt" ><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: test/xml<br />
Content-Description: application/vnd.opendap.org.dap4.xdp+xml; url=http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdp<br />
Content-Encoding: gzip<br />
X-DAP: 4.0<br />
</source><br />
</font><br />
<br />
For normative information on Atom, see [http://tools.ietf.org/html/rfc5023 RFC 5023] and [http://tools.ietf.org/html/rfc4287 RFC 4287].<br />
<br />
==== Example: Validated Atom Document with one atom:entry for a dataset, and an atom:link for each service ====<br />
<br />
<font size="2"><br />
<source lang="xml" ><br />
<br />
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><br />
<entry xmlns="http://www.w3.org/2005/Atom"><br />
<br />
<title>DatasetServices: ECMWF_ERA-40_subset.ncml</title><br />
<br />
<id>http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml</id><br />
<br />
<updated>2003-12-13T18:30:02-05:00</updated><br />
<br />
<author><br />
<name>Nathan Potter</name><br />
<email>johndoe@devnull.com</email><br />
</author><br />
<content type="xhtml" xml:lang="en" xml:base="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"><br />
<div xmlns="http://www.w3.org/1999/xhtml">DAP Dataset Services for http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml</div><br />
</content><br />
<br />
<link title="Dataset Services Description"<br />
rel="self"<br />
type="application/atom+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml"/><br />
<br />
<link title="DAP4 Dataset Metadata XML Document."<br />
rel="related"<br />
type="application/vnd.opendap.org.dap4.dmr+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dmr"/><br />
<br />
<link title="DAP4 Data object."<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap4.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dap"/><br />
<br />
<link title="OPeNDAP HTML Data Request Form for data sub-setting and access."<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.html" /><br />
<br />
<link title="DAP2 Data Object."<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap2.data" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dods"/><br />
<br />
<link title="DAP4 Data response in ASCII form."<br />
rel="enclosure"<br />
type="text/plain" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.asc"/><br />
<br />
<link title="NetCDF-3 file-out response."<br />
rel="enclosure"<br />
type="application/x-netcdf" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.nc"/><br />
<br />
<link title="XML Data Response"<br />
rel="enclosure"<br />
type="application/vnd.opendap.org.dap4.data+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.xdap"/><br />
<br />
<link title="DAP2 DDX document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.ddx+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ddx"/><br />
<br />
<link title="DAP2 DDS document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.dds" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.dds"/><br />
<br />
<link title="DAP2 DAS document"<br />
rel="related"<br />
type="application/vnd.opendap.org.dap2.dds" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.das"/><br />
<br />
<link title="RDF representation of the Dataset Metadata response."<br />
rel="related"<br />
type="application/rdf+xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rdf"/><br />
<br />
<link title="DAP2 Dataset Information Page"<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.info"/><br />
<br />
<link title="Server Version Document"<br />
rel="related"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.ver"/><br />
<br />
<link title="ISO 19115 Metadata Representation of the Dataset (DDX) response."<br />
rel="related"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.iso"/><br />
<br />
<link title="ISO 19115 Metadata Representation conformance score for this dataset."<br />
rel="related"<br />
type="text/html" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.rubric"/><br />
<br />
<link title="Dataset file access"<br />
rel="enclosure"<br />
type="text/xml" <br />
href="http://test.opendap.org:8090/opendap/hyrax/ECMWF_ERA-40_subset.ncml.file"/><br />
<br />
</entry><br />
<br />
<br />
</source><br />
</font><br />
--></div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9297DAP4 Web Services v32012-09-04T20:52:25Z<p>EthanDavis: /* DAP4 Error Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
A DAP4 error response must include the following information:<br />
<br />
* a standard code (?do we want to include a code, or is just the message enough?)<br />
* a message with information describing the error<br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9296DAP4 Web Services v32012-09-04T20:50:31Z<p>EthanDavis: /* DAP4 Error Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4 Error Response ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place. <br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9295DAP4 Web Services v32012-09-04T20:49:50Z<p>EthanDavis: /* Web Services */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== [[DAP4 Error Response]] ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place. <br />
<br />
==== Error Response Resource Role ====<br />
<br />
DAP4 Error Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/error</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Error Response ====<br />
<br />
The normative XML representation for the Error Response is defined in Appendix x "Normative XML Encoding of the Error Response". The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.error.xml'''</code></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9294DAP4 Web Services v32012-09-04T20:42:54Z<p>EthanDavis: /* DAP4 Error Responses */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
The standard DAP4 error resource role and encoding (plus a few alternate encodings) are: <br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9293DAP4 Web Services v32012-09-04T20:40:49Z<p>EthanDavis: /* DAP4 Error Responses */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard (normative) encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (Data):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
; Error Response (ER)<br />
: Role: <nowiki>http://services.opendap.org/dap4/error</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.error+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (Data)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (Data). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-services</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br />
<br />
==== Service Behavior ====<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DSR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DSR, '''or''' return an HTTP status of 404 to indicate that an HTML representation of the DSR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<!-- <br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
--><br />
<br />
=== Dataset Metadata Response <!--'''[[DAP4:_Responses#Dataset_Metadata_Response | DAP4: Dataset Metadata Response]]'''--> ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The DMR 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]] More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
==== DMR Resource Role ====<br />
<br />
DMRs are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Metadata Response is defined in the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dmr'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dmr''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the DMR for the (possibly constrained) dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DMR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-metadata+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DMR ====<br />
<br />
===== Downgrading the Normative XML Encoding (Required) =====<br />
While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
the response MUST be an the normative representation of the DMR along with the HTTP <font size="2"><code>Content-Type</code></font> header set to <font size="2"><code>text/.xml</code></font> . For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The normative XML representation of the DMR MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL ( and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP DMR URL with the suffix <font size="2"><code>'''.html'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dmr'''''.html'''</code></font><br/><br />
<br />
the server MUST reply with an HTML representation of the DMR, '''or''' return an HTTP status of 404 (or 415) to indicate that an HTML representation of the DMR is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 DMR URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DMR. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
Must return the HTML representation of the DMR, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
=== DAP4: Data Response <!--'''[[DAP4:_Responses#Data_Response | DAP4: Data Response ]]'''--> ===<br />
The Data Service provides DAP4 data access to a dataset, and is the (primary) way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is a binary document with MIME type ''application/vnd.opendap.org.dap4.data''. The payload is broken into two logical parts: A DMR-type xml document that describes the data and a BLOB that contains the actual data. For more on the internal structure of the Data response's payload, see [[DAP4: Encoding for the Data Response]] and [[DAP4: Chunked encoding]].<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
==== Data Response Resource Role ====<br />
<br />
DAP4 Data Responses are identified by the resource role:<br />
<br />
: '''<font size="2"><code><nowiki>http://services.opendap.org/dap4/data</nowiki></code></font>'''<br />
<br />
==== Normative Encoding of the Data Response ====<br />
<br />
The normative XML representation for the Data Response is defined in the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page. The media type for the normative XML representation is:<br />
<br />
: <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
<br />
(''More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.'' )<br />
<br />
==== Service Behavior ====<br />
Every DAP4 compliant server MUST return the normative representation ([[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix <font size="2"><code>'''.dap'''</code></font> added to it:<br />
<br />
: request url = <font size="2"><code>'''dataset_url + '.dap''''+ [?dap_constraint]</code></font><br/><br />
<br />
the server MUST reply with an normative representation of the (possibly constrained) data response for the dataset given these conditions:<br />
<br />
* the request "Accept" header contains only the normative XML encoding media type (<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>),<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the Data Response.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.data<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the Data Response ====<br />
<br />
===== ASCII Encoding (Optional) =====<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.ascii'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.ascii'''</code></font><br/><br />
<br />
the server MUST reply with the ASCII representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an ASCII representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the ASCII representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an ASCII encoded Data Response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source><br />
<br />
Must return the ASCII representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== XML Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.xml'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/xml; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
If available, the XML representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an XML encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
Must return the XML representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
===== NetCDF Encoding (Optional) =====<br />
<br />
When an HTTP GET request is made on a DAP Data Response URL with the suffix <font size="2"><code>'''.nc'''</code></font><br/> added to it:<br />
<br />
: request url = <font size="2"><code>''dataset_url.dap'''''.nc'''</code></font><br/><br />
<br />
the server MUST reply with the XML representation of the Data Response, '''or''' return an HTTP status of 404 (or 415) to indicate that an XML representation of the Data Response is not available. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dmr.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
Might result in the following response:<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/x-netcdf<br />
Date: ...<br />
</source><br />
<br />
If available, the NetCDF representation MUST also be returned when an HTTP GET request is made on a base DAP4 Data Response URL (without an additional suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an NetCDF encoded data response. For example this request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: application/x-netcdf<br />
</source><br />
<br />
Must return the NetCDF representation of the Data Response, if available. If no such representation is available then the server MAY return an HTTP status of 404 or even 415.<br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9144DAP4 Web Services v32012-08-23T15:59:17Z<p>EthanDavis: DSR: different role for different domains</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions.<br />
<br />
Each service (or response type) has a unique resource role (defined in the appropriate specification), each link (alternate representation) for a given service MUST fulfill that same role. This is not always a clear distinction to make. For example, the DMR can be mapped into ISO 19115 metadata. However, IS0 19115 is clearly a different domain.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9143DAP4 Web Services v32012-08-23T05:18:39Z<p>EthanDavis: /* Normative Encoding of the DSR */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the "Normative XML Encoding of the DSR" appendix. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9142DAP4 Web Services v32012-08-23T05:15:50Z<p>EthanDavis: /* Normative Encoding of the DSR */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the [[DAP4_Dataset_Services Response|DAP4 Dataset Services Response]] page (?or Appendix A "Normative XML Encoding of the DSR"?). The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9141DAP4 Web Services v32012-08-23T05:14:12Z<p>EthanDavis: /* Normative Encoding of the DSR */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the [[DAP4_Dataset_Services Response|DAP4 Dataset Services Response]] page. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9140DAP4 Web Services v32012-08-23T05:02:36Z<p>EthanDavis: /* DAP4 Dataset Services Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the [DAP4_Dataset_Services Response|DAP4 Dataset Services Response] page. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
For example, the request:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: application/vnd.opendap.org.dataset-services+xml<br />
Date: ...<br />
</source><br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
Might result in the following response:<br />
<br />
<source lang="httpd"><br />
HTTP/1.1 200 OK<br />
Content-Type: text/html; charset=utf-8<br />
Date: ...<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9138DAP4 Web Services v32012-08-23T04:52:54Z<p>EthanDavis: /* Web Services */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
==== DSR Resource Role ====<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
==== Normative Encoding of the DSR ====<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the [DAP4_Dataset_Services Response|DAP4 Dataset Services Response] page. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
==== Other Encodings of the DSR ====<br />
<br />
===== Downgrading the Normative XML Encoding =====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
===== HTML Encoding =====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9136DAP4 Web Services v32012-08-23T04:51:28Z<p>EthanDavis: /* DAP4 Dataset Services Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services_Response | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
=== DSR Resource Role ===<br />
<br />
DSRs are identified by the resource role:<br />
<br />
: '''<nowiki>http://services.opendap.org/dap4/dataset-services</nowiki>'''<br />
<br />
=== Normative Encoding of the DSR ===<br />
<br />
The normative XML representation for the Dataset Services Response is defined in the [DAP4_Dataset_Services Response|DAP4 Dataset Services Response] page. The media type for the normative XML representation is<br />
<br />
: '''application/vnd.opendap.org.dataset-services+xml'''<br />
<br />
When an HTTP GET request is made on a base DAP4 dataset URL, all DAP4 servers MUST return the normative XML encoding of the DSR given these conditions: <br />
<br />
* the request "Accept" header contains only the normative XML encoding media type,<br />
* the request "Accept" header equals "*/*", or<br />
* the request "Accept" header does not indicate a preference for another media type in which the server knows how to encode the DSR.<br />
<br />
=== Other Encodings of the DSR ===<br />
<br />
==== Downgrading the Normative XML Encoding ====<br />
<br />
When ...<br />
<br />
: '''.xml'''<br />
<br />
the response ...<br />
<br />
A server MAY ...<br />
For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source><br />
<br />
==== HTML Encoding ====<br />
<br />
When an HTTP GET request is made on a base DAP dataset URL with the suffix:<br />
<br />
: '''.html'''<br />
<br />
the response MUST be an HTML representation of the DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source><br />
<br />
The HTML representation MUST also be returned when an HTTP GET request is made on a base DAP4 dataset URL (without a suffix) and the server uses server-driven content negotiation to decide that the best response for the client would be an HTML encoded DSR. For example:<br />
<br />
<source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source><br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services_Response | Dataset Services Response ]] servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9133DAP4 Web Services v32012-08-23T04:12:07Z<p>EthanDavis: /* DAP4 Dataset Services Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides clients with a listing of all available DAP4 services and all the available encodings for those services as well as all available DAP4 extensions. <br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
To take advantage of web caching, servers should try to keep DSRs light weight (i.e., quick creation) and as stable as possible.<br />
<br />
DSR can be identified by their resource role:<br />
<br />
'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>''' <br />
<br />
=== [[DAP4 Dataset Services Response]] (Original) ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services | Dataset Services ]] response servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9132DAP4 Web Services v32012-08-23T03:48:43Z<p>EthanDavis: Undo revision 9131 by EthanDavis (talk)</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
To take advantage of web caching, capabilities documents should try to be light weight (i.e., quick creation) and as stable as possible. <br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services | Dataset Services ]] response servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9131DAP4 Web Services v32012-08-23T03:47:12Z<p>EthanDavis: /* DAP4 Resource Roles and Encodings */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: '''<nowiki>http://services.opendap.org/dap4/dataset-service</nowiki>'''<br />
: Media types:<br />
:* '''application/vnd.opendap.org.dataset-services+xml'''<br />
:* '''text/xml''' (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: '''application/vnd.org.opendap.dap4.dataset-metadata+xml'''<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
To take advantage of web caching, capabilities documents should try to be light weight (i.e., quick creation) and as stable as possible. <br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services | Dataset Services ]] response servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavishttps://docs.opendap.org/index.php?title=DAP4_Web_Services_v3&diff=9130DAP4 Web Services v32012-08-23T03:29:44Z<p>EthanDavis: /* DAP4 Dataset Services Response */</p>
<hr />
<div>[[Category:Development|Development]][[Category:DAP4|DAP4]]<br />
[[OPULS_Development| << Back to OPULS Development]]<br />
== Introduction ==<br />
<br />
This document defines the DAP4 Web Service protocol which DAP4-compliant software MUST support when utilizing the HTTP protocol to transmit DAP4 requests and responses, along with additional optional services that DAP4-compliant software SHOULD support.<br />
<br />
The DAP4 protocol uses three basic responses to represent a data resource. One response, the Dataset Metadata Response(DMR) contains metadata information describing the structure of the data resource. That is, it characterizes the variables, their datatypes, names and attributes. The second response, the Data Response(DataDMR), contains both the metadata about the requested data and the actual data that was requested. The third basic response is the Dataset Services Response (DSR) that provides a listing of services, any alternate media representations if available, and all of the associated access URI's for a particular data resource.<br />
<br />
The DAP4 protocol uses a fourth basic resource, the Constraint/Query Expression (CE), to represent subsetting of and, possibly, transformations of the dataset requested.<br />
<br />
The DAP4 Data Model, constraint/query language, dataset metadata XML encoding, and binary data encoding are all defined in the DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints" document [[#DAP4_Vol1|[DAP4_Vol1]]]<br />
<br />
Each of the three responses (Dataset Metadata, Data, and Dataset Services) are complete in and of themselves so that, for example, the Data response can be used by a client without ever requesting either of the two other responses. In many cases, client programs will request the Dataset Metadata response before requesting the Data response but there is no requirement they do so and servers SHALL NOT require that behavior on the part of clients.<br />
<br />
These three standard dataset responses can each be accessed in two different ways. First, similar to DAP2 URL construction and to support client-driven content negotiation (see the 3.? "Content Negotiation" section below), each dataset resource has a standard URL suffix that can be added to the DAP4 dataset URL to retrieve the resource in its standard encoding. This allows clients, given a base DAP4 dataset URL, to construct DAP4 URLs in a simple and standard way for each of the three standard dataset resources.<br />
<br />
Second, to support server-driven content negotiation (see the 3.? "Content Negotiation" section below) and a more hypermedia-driven style, a DAP4 resource role is defined for each standard dataset resource and a DAP4 media type is defined for each dataset resource encoding scheme.<br />
<br />
Any particular instance of a DAP4 server MAY have one or more additional services, alternate media representations of service responses, or unique (to the server instance) server side functions. All of these things, including the core services and their default representations MUST be included in the [[DAP4_Dataset_Services | Dataset Services Response]].<br />
<br />
The DAP4 web service is currently limited to HTTP GET requests though it is expected that extensions (e.g., asynchronous access) will use other HTTP methods (e.g., POST). This makes, for now, the DAP4 Constraint Expression something of a pseudo-resource type given that they are encoded as part of the URL query string rather than as an independent document.<br />
<br />
=== DAP4 Resource Roles and Encodings ===<br />
<br />
The standard DAP4 dataset resource roles and encodings (plus a few alternate encodings) that are defined in the core DAP4 documents are:<br />
<br />
; Dataset Services Response (DSR)<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-service</nowiki><br />
: Media types:<br />
:* application/vnd.opendap.org.dataset-services+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Metadata Response (DMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/dataset-metadata</nowiki><br />
: Media types:<br />
:* application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:* text/xml (same encoding as above but more generic media type)<br />
:* text/html<br />
; Dataset Data Response (DataDMR):<br />
: Role: <nowiki>http://services.opendap.org/dap4/data</nowiki><br />
: Media types:<br />
:* HTTP Content-Type: application/vnd.org.opendap.dap4.data<br />
:** MIME part I: application/vnd.org.opendap.dap4.dataset-metadata+xml<br />
:** MIME part II: application/vnd.org.opendap.dap4.data.big-endian<br />
:* text/plain (ASCII data response)<br />
:* text/xml (XML data response)<br />
<br />
The core DAP4 documents are:<br />
<br />
* DAP4 Volume 1: "Data Model, Persistence Representations, and Constraints"<br />
* DAP4 Web Service (this document)<br />
* DAP4 Dataset Services<br />
* DAP4 Requirements for Server-side Functions<br />
<br />
=== DAP4 Error Responses ===<br />
<br />
The DAP4 protocol returns error information using an Error response. If a request for any of the three basic responses cannot be completed then an Error response is returned in its place.<br />
<br />
=== Extensions to DAP4 Core Specifications ===<br />
Several types of extensions can be made to the DAP4 core including:<br />
<br />
* New encodings for the core DAP4 response types<br />
* New response types<br />
* New server-side functions.<br />
<br />
== Terms and Definitions ==<br />
<br />
; Dataset Service Response (DSR)<br />
: The DAP4 response type that contains a list of DAP (and other) services available for the dataset including any alternate media representations and all the associated access URIs.<br />
; Dataset Metadata Response (DMR)<br />
: The DAP4 response type that contains metadata information describing the structure of the requested data. The metadata information characterizes the requested data variables including their names, data types, shapes, and attributes.<br />
; Dataset Data Response (DataDMR)<br />
: The DAP4 response type that contains both the dataset metadata and the binary data for the requested data.<br />
; Resource role ID<br />
: A URI that identifies the role of a resource, generally provided with a link to allow clients to identify the type of resource the link references. (For instance, an "atom:link" element has an optional "atom:rel" attribute.)<br />
; Media Type<br />
: A internet media type is a two-part identifier for resource encoding schemes [http://en.wikipedia.org/wiki/Internet_media_type]. (E.g., "text/html", "text/plain", "application/octet-stream".)<br />
<br />
== Web Services == <br />
<br />
The core of the DAP4 Web Service protocol consists of the three standard response types: Dataset Services Response (DSR), Dataset Metadata Response (DMR), and Dataset Data Response (DataDMR). Each dataset served by a DAP4 compliant server MUST provide these three response types.<br />
<br />
All of the example requests described below are based on the DAP4 dataset URL:<br />
: http://server.org:8080/dap/path/data.nc<br />
<br />
=== [[DAP4 Dataset Services Response]] ===<br />
<br />
The DAP4 Dataset Services Response (DSR) provides a listing of the various DAP4 resources and their associated media-type representations available for a dataset. Dereferencing the base URL for a dataset accessed through a DAP4 web server will return a ''DatasetServices'' document that describes the various responses possible for that data set, including URLs that can be used to access those responses. In other words, the Dataset Services response is acquired by dereferencing the data resource (aka base) URL for the dataset and there is no suffix added to the data resource URL prior to that dereferencing.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4 Dataset Services Response | as described here]]) of the Dataset Services response when a client attempts to access an unmodified dataset URL. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
The Dataset Services Response MUST contain the following information:<br />
<br />
* List of DAP versions supported by server<br />
* The implementation version (e.g., "TDS 4.3.57" or "Hyrax 1.7.45")<br />
* List of all available DAP4 services for the dataset<br />
* For each DAP4 services listed, a list of all available links each with its corresponding media type<br />
* List of supported extensions<br />
** Resource type extensions<br />
** Media type extensions<br />
** Server-side function extensions<br />
<br />
If SHOULD contain the following information:<br />
<br />
* A human readable title for the dataset<br />
* Human readable titles for each service<br />
<br />
More information on the normative XML representation for the Dataset Services Response can be found on the [[DAP4 Dataset Services Response]] page.<br />
<br />
To take advantage of web caching, capabilities documents should try to be light weight (i.e., quick creation) and as stable as possible. <br />
<br />
service suffix = <br /><br />
service url = <font size="2"><code>'''dataset_url'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-services#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font><br/><br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.html'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the normative XML representation of the Dataset Web Services response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it MAY return it's normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Services response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-services+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Services response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Services response. The server MUST response with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Dataset Metadata Response | DAP4: Dataset Metadata Response]]''' ===<br />
The Dataset Metadata Service returns the Dataset Metadata Response (DMR) which is a metadata description of the dataset. The normative representation of the DMR is an XML document that contains both the 'syntactic' (structural) and 'semantic' metadata for the dataset, persisted as a [[DAP4: Data Model]] representation of the dataset held at the server. The Dataset Metadata 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. 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.<br />
Note that [[DAP4:_Responses#Transmitting_Attributes_in_constrained_Dataset_documents | All dap:Attribute objects have been removed from constrained dap:Dataset objects.]]<br />
<br />
Every DAP4 compliant server MUST return the normative representation (an XML document [[DAP4: Data Model | as described here ]]) of the Dataset Metadata Response when a client attempts to access a dataset URL with the suffix ".dmr" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
<br />
* More information on the DMR can be found on the [[DAP4: Responses#Dataset Response | DAP4: Responses]] page.<br />
<br />
* More information on the syntax of DAP4 constraint expressions can be found on [[DAP4:_Data_Model#Constraint_Expressions | DAP4: Data Model]] page.<br />
<br />
<br />
service suffix = <font size="2"><code>'''.dmr'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dmr' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/dataset-metadata#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/html'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.html'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dmr'''''.xml'''</code></font><br/><br />
<br />
==== HTTP Request Examples ====<br />
<br />
<br />
''Simple''<br />
: This simple request will return the XML representation of the Dataset Metadata response with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation for the HTML representation.''<br />
: This request for the Dataset Metadata response indicates that the client wants the HTML representation. The server SHOULD reply with the HTML representation if it is available, otherwise it may return the normative XML representation.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/html<br />
</source></font><br />
<br />
<br />
''Server-driven content negotiation for the XML representation.''<br />
: This request for the Dataset Services response indicates that the client wants the XML representation. The server MUST reply with the XML representation, and the server should set the <font size="2"><code>'''Content-Type'''</code></font> header to <font size="2"><code>'''text/xml'''</code></font>. While the normative representation of the the Dataset Metadata response is already an XML document, the normative media type is <font size="2"><code>'''application/vnd.opendap.org.dataset-metadata+xml'''</code></font> which may be unfamiliar to many generic clients (such as web browsers) and it is quite conceivable that such a client might ask for the more generic <font size="2"><code>'''text/xml'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml <br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation for the HTML representation.''<br />
: This request is for the HTML version of Dataset Metadata response. The server MUST reply with the HTML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''text/html'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.html HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
<br />
''Agent-driven content negotiation for the XML representation.''<br />
: This request is for the XML version of Dataset Metadata response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
=== '''[[DAP4: Data Response ]]''' ===<br />
The Data Service provides DAP4 data access to a dataset, and is the way that DAP4 returns data to a client. The Data service accepts a query string (constraint expression) which allows you to subset the data and invoke server side functions. When the service is invoked it returns the DAP4 data object. On the wire this is 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.<br />
<br />
Every DAP4 compliant server MUST return the normative representation (a multi-part MIME document [[DAP4: Data Model | as described here ]]) of the Data Response when a client attempts to access a dataset URL with the suffix ".dap" appended to it. The DAP4 server MAY return alternate representations if the client indicates that it can accept them and the server can provide them.<br />
<br />
More information on the Data response can be found on the [[DAP4:_Responses#Data_Response | DAP4: Responses]] page.<br />
<br />
suffix = <font size="2"><code>'''.dap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data#</nowiki>'''</code></font><br/><br/><br />
<br />
DAP4 media type:<br />
*<font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font><br/><br />
** First Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.dataset-metadata+xml'''</code></font><br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.big-endian'''</code></font> (For big endian encoded binary responses) <br/><br />
** Second Part: <font size="2"><code>'''application/vnd.org.opendap.dap4.data.little-endian'''</code></font> (For little endian encoded responses)<br/><br />
<br />
<br />
Alternate media type(s):<br />
*<font size="2"><code>'''text/ascii'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.ascii'''[?dap_constraint]'''</code></font><br/><br />
*<font size="2"><code>'''text/xml'''</code></font><br/><br />
:media type suffix = <font size="2"><code>'''.xml'''</code></font><br/><br />
:url = <font size="2"><code>''dataset_url.dap'''''.xml'''</code></font><br/><br />
<br />
<br />
<br />
==== HTTP Request Examples ====<br />
<br />
''Simple''<br />
: This simple request will return the full contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Simple with constraint''<br />
: This simple request will return the a subset of the contents of the dataset resource as a DAP4 data object with the <font size="2"><code>'''Content-Type'''</code></font> header of the response set to <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font>.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?proj=u,v,z&sel=z<300&sel=z>10 HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
''Server-driven content negotiation, ASCII data response''<br />
: This request for the Data response response indicates that the client wants the ASCII representation. The server SHOULD reply with the ASCII representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/plain<br />
</source></font><br />
<br />
''Server-driven content negotiation, XML data response''<br />
: This request for the Data response response indicates that the client wants the XML representation. The server SHOULD reply with the XML representation if it is available, otherwise it may return the normative binary multipart mime document known specifically as the <font size="2"><code>'''application/vnd.org.opendap.dap4.data'''</code></font> media type.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dmr HTTP/1.1<br />
Host: server.org:8080<br />
Accept: text/xml<br />
</source></font><br />
<br />
''Agent-driven content negotiation, ASCII data response''<br />
: Client requests the ASCII representation of the DAP4 data response. The server MUST reply with the ASCII representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/plain'''</code></font>)if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.ascii HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
<br />
''Agent-driven content negotiation, XML data response''<br />
: Client requests the XML representation of the DAP4 data response. The server MUST reply with the XML representation (with the <font size="2"><code>'''Content-Type'''</code></font> header of the respons set to <font size="2"><code>'''text/xml'''</code></font>) if available, or with a status of 404 if not..<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap.xml HTTP/1.1<br />
Host: server.org:8080<br />
Accept: */*<br />
</source></font><br />
<br />
== HTTP ==<br />
<br />
The DAP4 Web Services specification describes the features of HTTP that are required to be a compliant DAP4 client or server. It does not attempt to describe all aspects of HTTP that DAP4 servers might implement or that DAP4 clients may see in response to DAP4 requests. Similarly, it does not cover all issues related to the performance and scalability of HTTP.<br />
<br />
However, the following sections include both DAP4 requirements as well as some suggestions of HTTP features that servers and clients are encouraged to use.<br />
<br />
=== Content Negotiation and Media Types ===<br />
<br />
Though the DAP4 core specifications only describe one encoding for each type of resource, DAP4 web servers MAY have the ability to provide a given resource in a number of different media types. All media types available for a resource MUST be listed in the DAP4 Dataset Services response document.<br />
<br />
DAP4 responses MUST use the "Content-Type" header field to identify the media type of the DAP4 response body. For example, the normative value for the XML encoded DDX response is ''application/vnd.org.opendap.ddx+xml''.<br />
<br />
The DAP4 Dataset Services response describes the available services and their media types and provides DAP4 software (client and/or server) with two different mechanisms to negotiate for different kinds of media representations. The first of these is server-driven content negotiation as described in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP 1.1 specification, section 12 "Content Negotiation"]. The second is similar to the agent-driven negotiation also described in section 12 of the HTTP 1.1 specification. The difference being that the "list of available representations ... [each with] its own URI" is provided by the DAP4 Dataset Services response rather than in response to an initial request. <br />
<br />
Clients need not retrieve the Dataset Services response in order to access the normative representations of either the Dataset Metadata or Data responses, as these responses are required for every DAP4 server and are mapped to well known URL patterns. If clients attempt to access other representations or other services using agent-driven negotiation without first checking the Dataset Services response, they should be prepared to receive a 404 Not Found response.<br />
<br />
When using server-driven negotiation, DAP4 clients are encouraged to, at a minimum, include "Accept" and "User-Agent" headers in their requests and to provide accurate and detailed information in the values of those headers. However, when server-driven negotiation is used, DAP4 servers are not limited to those headers for determining the media type that is returned. DAP4 clients should also be prepared to handle 415 "Unsupported Media type" response codes.<br />
<br />
<!--<br />
When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type:<br />
<br />
<blockquote><br />
It is impossible for the server to accurately determine what<br />
might be "best" for any given user, since that would require<br />
complete knowledge of both the capabilities of the user agent<br />
and the intended use for the response (e.g., does the user want<br />
to view it on screen or print it on paper?).<br />
</blockquote><br />
<br />
<br />
<font color="red"><br />
When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
</font><br />
<br />
{| class="wikitable" width="85%"<br />
|+ Server Driven Negotiation Debate (NEEDS RESOLVED)<br />
! Ethan's View<br />
! James' View<br />
|-<br />
|When using server-driven negotiation DAP4 servers MAY return a more general media type (e.g., "text/xml") if something in the request (e.g., the "Accept" or "User-Agent" header values) indicates the client might be better able to handle a more general media type. Servers should use caution when downgrading the response media type: <br/><br/>"''It is impossible for the server to accurately determine what might be "best" for any given user, since that would require complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?).''"<br />
| style="width: 50%;" | When DAP4 servers engage in server-driven content negotiation they SHOULD only return DAP4 media types to clients that explicitly request them, otherwise they should return the most general media type that correctly represents the response content. In particular if a DAP4 server detects that a general purpose web browser (such as Internet Explorer, Firefox, Chrome, Safari, Opera, etc.) is requesting one of the three DAP4 response types then the Content-Type header in the servers response SHOULD be the most widely understood media type for the particular response. For the Dataset Services response and Dataset Metadata response this would be a media type of ''text/xml'' and for the Data response it would be ''multipart/mixed''. This is particularly important for the Dataset Services response and Dataset Metadata response as these XML documents may come with XSLT style sheet references that would allow the browser to transform the XML content into an HTML presentation suitable for the browsers. This presentation may even include a complete data request form that will allow the user to subset and select data in their browser. If the DAP4 specific media types are returned the browsers will simply write the response to disk and they will make no effort to render the response in the browser using the stylesheet reference.<br />
<br />
|}<br />
==== A brief digression on ''vnd'' MIME types ====<br />
Looking at how web browsers use these types, the set of vendor MIME types appears to be driven by the browsers, and not the servers. For example, Chrome will look for a MIME type of ''application/vnd.google.drive.ext-type.png'' and do something special when it sees it. Unless we expect mass-market HTTP client software to recognize ''vnd.opendap...'' MIME types, there's little value in them. This conclusion matches what the developers in NASA came to conclude with respect to the vendor MIME types when used as values for the Content-Type header. It's certainly the case that these MIME types provide no value to DAP-aware clients. Providing responses with Content-Type of ''text/xml'' will result in a browser rendering the response, something we might make actually useful with some savvy coding (for example, the (in)famous web form interface could be encoded in it using an XSL transform).<br />
<br />
--><br />
<br />
=== Redirects ===<br />
<br />
While HTTP redirects are not directly part of the DAP4 web protocol it is strongly suggested that DAP4 client implementations be capable of processing HTTP redirects as nominally described in the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP specification] sections on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 redirection status codes] and [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30 response headers] (It is suggested that implementers of DAP4 clients utilize an existing robust HTTP client library that will manage this for them.)<br />
<br />
=== Caching of Responses and Conditional Requests ===<br />
<br />
While, HTTP caching and conditional requests are not explicitly part of the DAP4 web protocol, they do provide important tools for improving the performance of both sides client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 HTTP caching] works, and utilize it for working with DAP servers.<br />
<br />
=== Authentication/Authorization ===<br />
<br />
Authentication is the process by which a user agent establishes the identity of the user to a server, and the server establishes it's identity with the user agent. While, HTTP authentication is not explicitly part of the DAP4 web protocol, it does provide important tools for securing the client server interaction. Therefore, it is strongly suggested that DAP4 servers and client implementers be aware of how [http://www.ietf.org/rfc/rfc2617.txt HTTP authentication] works, and utilize it for working with DAP servers. Server implementers should pay particular attention to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15 HTTP security considerations].<br />
<br />
Authorization is the process through which a server determines who/what has access to its various holdings and services. The HTTP protocol does not directly address the issue of authorization (even though HTTP defines the 401 response status using the word "authorization" it does not provide separate semantics for authentication and authorization which we see as an important distinction for data access), but any DAP4 server implementer should be aware that some kind of mechanism for controlling access to holdings and services will likely be desired by the people that install and operate their software.<br />
<br />
=== Headers ===<br />
<br />
==== Request Headers ====<br />
<br />
These are the HTTP request headers that DAP clients using HTTP MAY utilize. DAP4 servers MUST accept these headers and act on them in a manner consistent with their descriptions below.<br />
<br />
===== General =====<br />
:; Accept<br />
:: The HTTP Accept header MAY be used by clients that wish to engage in server-dirven content negotiation by requesting a particular representation of a resource in the initial request. The server MUST utilize this header, if present, in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 HTTP content negotiation] specification.<br />
<br />
:; User-Agent<br />
:: The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43 HTTP User-Agent header] MAY be used by clients to indicate their "software identity" to the server. The server MAY utilize this header, if present, to alter the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Content-Type] of the response to something that is more likely to be digestible by the requesting client software.<br />
<br />
===== DAP Specific =====<br />
<br />
:There are no DAP specific headers required to make a general DAP request.<br />
<br />
===== Asynchronous Transaction =====<br />
; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#Accept_DAP_Asynchronous_Response | X-DAP-Async-Accept]]<br />
: A client MAY indicate it's willingness to accept asynchronous responses by including the '''X-DAP-Async-Accept''' HTTP header. Clients MAY make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait by using the '''X-DAP-Async-Accept''' HTTP header with a value given in seconds. A value of zero indicates that the client is willing to accept whatever delay the server may encounter.<br />
<br />
==== Response Headers ====<br />
<br />
These are the HTTP response headers that DAP servers using HTTP MUST and SHOULD (as indicated) return.<br />
<br />
===== General =====<br />
<br />
:; Date<br />
:: DAP4 servers MUST return an HTTP '''Date''' header whose value is the time of the response and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Last-Modified<br />
:: DAP4 servers SHOULD return an HTTP '''Last-Modified''' header whose value is the last modified time of the request resource and which MUST be in [http://www.ietf.org/rfc/rfc1123.txt RFC 1123] format.<br />
<br />
:; Content-Type<br />
:: DAP4 servers MUST return an HTTP '''Content-Type''' header, the value of which SHOULD be set in accordance with the [[#Media_Types | Media Types discussion]] above.<br />
<br />
:; Content-Description<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Description''' header. <br />
<br />
:; Content-Disposition<br />
:: DAP4 servers SHOULD return an HTTP '''Content-Disposition''' header when transmitting file typed responses.<br />
<br />
:; Content-Encoding<br />
:: DAP4 servers MUST return an HTTP '''Content-Encoding''' header when the content-coding of an entity is not "identity".<br />
<br />
<br />
<!--<br />
<br />
<font color="Red">Update this to include the following headers....</font><br />
<font size="2"><pre><br />
HTTP/1.1 200 OK<br />
Date: Mon, 23 May 2005 22:38:34 GMT<br />
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT<br />
Content-Type: multipart/related; type="text/xml"; start="<<start id>>"; boundary="<<boundary>>"<br />
Content-Description: data-ddx; url=...<br />
Content-Encoding: gzip<br />
XDAP: <<DAP version>><br />
</pre></font><br />
<br />
--><br />
<br />
===== DAP Specific =====<br />
<br />
:; X-DAP-Server<br />
:: DAP4 servers SHOULD return the '''X-DAP-Server''' HTTP header. This HTTP header is used in a response to communicate the software version of the server. This may be a simple string with the server name and version number, or multiple software component versions may be represented. The value of this header is a string determined by the implementations author(s).<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: bes/3.10.0, libdap/3.11.2, dap-server/ascii/4.1.2, csv_handler/1.0.2, freeform_handler/3.8.4, fits_handler/1.0.7, fileout_netcdf/1.1.2, gateway_module/1.1.0, hdf4_handler/3.9.4, hdf5_handler/1.5.0, netcdf_handler/3.10.0, ncml_module/1.2.1, dap-server/usage/4.1.2, dap-server/www/4.1.2, xml_data_handler/1.0.1</tt></font><br />
<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP-Server: TDS-4.19.3</tt></font><br />
<br />
:; X-DAP<br />
:: DAP4 servers MUST return the '''X-DAP''' HTTP header. This HTTP header is used in a response to indicate the DAP protocol version used to encode the content of the response. This value is constrained to a format of ''"major_version" dot "minor version"'', where both major_version and minor_version are represented by an integer value.<br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 4.0</tt></font><br />
:: '''Example'''<br />
::: <font size="2"><tt>X-DAP: 2.17</tt></font><br />
<br />
===== Asynchronous Transaction =====<br />
<br />
:; [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP_Asynchronous_Response_Required | X-DAP-Async-Required]] <br />
:: DAP4 servers MUST return the '''X-DAP-Async-Required''' header if the request requires an asynchronous response and the client has not indicated willingness to accept such a response. Rejection of the request should also be indicated by the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP_Asynchronous_Response_Required | 400 DAP Asynchronous Response Required]] HTTP response code.<br />
<br />
=== Status Codes ===<br />
<br />
DAP servers that provide an HTTP interface are expected to utilize the HTTP response codes in a manner consistent with the [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTTP 1.1 specification]. <br />
<br />
The ones that are detailed here are used by the DAP in a manner consistent with the specifications definition, but in support of specific DAP server behavior.<br />
<br />
==== 200 OK ====<br />
<br />
A server MUST return an HTTP status of 200 when the request has been successful and that the returned document contains the requested resource. However since DAP responses can be quite large and since it is also possible for the server to encounter any number of problems during the marshaling, serialization, and subsequent transmission of the response it is possible that the server may have committed/transmitted the HTTP headers (in which the status value is transmitted) before a subsequent error is encountered. These types of errors are transmitted in the DAP4 over-the-wire protocol and all DAP4 clients MUST be able to read and process these errors. <font color="red">See Section?</font><br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#202_Accepted | 202 Accepted]] ====<br />
<br />
A server MUST return a '''202 Accepted''' HTTP response code when a request has been accepted and will be handled asynchronously. The response body MUST contain a [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Accepted | DAP asynchronous response accepted]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400 Bad Request] ====<br />
<br />
The HTTP specification defines this status code as:<br />
:''The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.''<br />
DAP servers utilizes this code to mean one of two things.<br />
<br />
===== 400 Bad DAP4 Request Syntax =====<br />
<br />
:The '''400 Bad DAP4 Request Syntax''' HTTP response code MUST be returned by the server when there is a problem with the syntax of the OPeNDAP URL. The problem could be in the formulation of the constraint expression, or it may be that the URL extension did not match any that are recognized by this server.<br />
<br />
===== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#400_DAP4_Asynchronous_Response_Required | 400 DAP4 Asynchronous Response Required]] =====<br />
<br />
:The '''400 DAP4 Asynchronous Response Required''' HTTP response code MUST be returned by the server when the DAP request has been rejected because an asynchronous response is required and the client did not indicate willingness to accept an asynchronous response. The server MUST include the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Required | X-DAP-Async-Required]]''' HTTP header and the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Required | DAP4 Asynchronous Response Required]] document as the response body.<br />
<br />
==== 401 Unauthorized ====<br />
<br />
The '''401 Unauthorized''' HTTP response code MUST be returned by the server when access to the requested resource requires (not previously acquired) user authentication. See the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP specification] for usage and behavior.<br />
<br />
==== 403 Forbidden ====<br />
<br />
The '''403 Forbidden''' HTTP response code MUST be returned when the server has understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. This is appropriate to return if, for example, the server software does not have read permission for the requested resource.<br />
<br />
==== 404 Not Found ====<br />
The '''404 Not Found''' HTTP response code MUST be returned when the server has not found anything matching the Request-URI.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#409_Conflict_-_DAP4_Response_Not_Ready | 409 Conflict (DAP4 Async Response Not Available)]] ====<br />
The '''409 Conflict''' HTTP response code SHOULD be returned by the server when the DAP request has been rejected because a previous asynchronous request has not been completed and the result is not ready for access. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Response_Not_.28Yet.29_Available | DAP4 Asynchronous Response Not Yet Available]] document.<br />
<br />
==== [[DAP4:_Asynchronous_Request-Response_Proposal_v3#412_Precondition_Failed | 412 Precondition Failed]] ====<br />
<br />
The '''412 Precondition Failed''' HTTP response code MUST be returned by the server if the DAP request has been rejected because it did not meet the '''[[DAP4:_Asynchronous_Request-Response_Proposal_v3#X-DAP-Async-Accept | X-DAP-Async-Accept]]''' condition that was specified in the request. The response body MUST contain the [[DAP4:_Asynchronous_Request-Response_Proposal_v3#DAP4_Asynchronous_Request_Rejected | DAP4 Asynchronous Request Rejected]] document.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16 415 Unsupported Media Type] ====<br />
<br />
The '''415 Unsupported Media Type''' HTTP response code MUST be returned when the client requests a representation of the requested resource that the server cannot provide.<br />
<br />
==== [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] ====<br />
<br />
The [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1 500 Internal Server Error] SHOULD be returned when the DAP server encounters internal problems when attempting to fulfill a request.<br />
<br />
=== Verbs (aka Methods) ===<br />
<br />
==== GET ====<br />
<br />
A DAP request may be made using the HTTP GET request method utilizing a Uniform Resource Identifier (URI) that encodes information specific to the DAP (<font color="red">see Section ?</font>). <br />
<br />
Each GET request MUST conform to the HTTP specification (which basically says that a GET request MUST contain an HTTP protocol version number followed by a MIME-like message containing various headers that further describe the request.). While there are some optional [[#Request_Headers | DAP HTTP request headers]] that may be used, DAP requests do not require specific HTTP headers beyond those necessary for HTTP. DAP servers SHOULD support the use of the HTTP Accept request header to allow clients to engage in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html HTTP content negotiation] for specific representations of a DAP response.<br />
<br />
; Implementation Note<br />
:''In practice, DAP clients typically use a third-party library implementation of HTTP/1.1 so the GET request, URI and HTTP version information are hidden from the client; it sees only the DAP Uniform Resource Locator (URL) and the request headers.''<br />
<br />
The DAP server responds to the GET request with an HTTP compliant response (one that includes a status line containing the HTTP protocol version and an error or success code, followed by HTTP response headers and then response itself). There are two DAP specific HTTP headers that are always included in a DAP response over HTTP: <font size="3"><tt>X-DAP-Server</tt></font> and <font size="3"><tt>X-DAP</tt></font>, [[#Response_Headers | as described above]]. The DAP response is the payload of the HTTP response. Unless otherwise negotiated, the data response payload is encoded in multpart-MIME format, while the other responses are simple HTTP responses <font color="red">This is further described in Section ?.</font><br />
<br />
===== Examples =====<br />
; HTTP GET request.<br />
<font size="2"><source lang="httpd"><br />
GET /dap/path/data.nc.dap?u,v[0:8:1024] HTTP/1.1<br />
Host: server.org<br />
Accept: application/vnd.org.opendap.dap4.data<br />
</source></font><br />
<br />
<!--<br />
<br />
==== POST ====<br />
<br />
DAP4 supplies (via the DAP Service Terminus) a URI for each DAP4 service and each of its various media-type representations. How do we leverage this into a non-HTTP usage? I think we need to define a message document that is sent to the server (say over a socket) that carries everything we need in the request. Suggestion:<br />
<br />
<font size="2"><source lang="xml"><br />
<request xmlns="http://opendap.org/ns/dap4/request"><br />
<service>dap4-data</service><br />
<media-type>...</media-type><br />
<dataset id="/local/id/of/data/resource"><br />
<ce><br />
<projection>x,y[0:3:99]</projection><br />
<selection>k<33 & i>17</selection><br />
</ce><br />
</dataset><br />
</request><br />
</source></font><br />
<br />
Obviously this needs more thought and discussion...<br />
<br />
<br />
<br />
'''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. <br />
<br />
'''Discussion''': <br />
<br />
# Does this matter?<br />
# Would we need to add new syntax server-side functions etc. to the protocol to enable this?<br />
--><br />
<br />
<br />
<br />
== Normative References ==<br />
<br />
<div id="DAP4_Vol1"></div><br />
<nowiki>[DAP4_Vol1]</nowiki> [[DAP4 Volume 1|DAP4 Volume 1: "Data Model, Persistent Representations, and Constraints"]].<br />
<br />
<div id="HTTP_RFC2616"></div><br />
<nowiki>[HTTP_RFC2616]</nowiki> "Hypertext Transfer Protocol -- HTTP/1.1" (as [http://www.ietf.org/rfc/rfc2616.txt text] or [http://www.w3.org/Protocols/rfc2616/rfc2616.html HTML]).<br />
<br />
== Non-Normative References ==<br />
<br />
<div id="REST_Fielding"></div><br />
[REST] R. Fielding, UC Irvine Doctoral Thesis: [http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm|"Architectural Styles and the Design of Network-based Software Architectures"]<br />
<br />
== Extra Web Service Stuff ==<br />
=== Other Common Services ===<br />
<br />
DAPx servers typically offer a number of other services that, while not exactly DAP services, are commonly available. This section lists just some of the alternate services a DAP4 server might provide. By enumerating the available services in the [[DAP4_Dataset_Services | Dataset Services ]] response servers can easily make clients (either software and monkey) aware of their ancillary capabilities.<br />
<br />
==== [[DAP4: HTML DATA Request Form Service]] ====<br />
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 .<br />
<br />
<br />
suffix = <font size="2"><code>'''.html'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .html'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/data-request-form#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font> | <font size="2"><code>'''text/xhtml'''</code></font><br/><br />
<br />
==== [[DAP4: RDF Service | DAP4: RDF Service]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.rdf'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rdf'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/rdf#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/rdf+xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO 19115 Service ]] ====<br />
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: Responses#Dataset_Response | DAP4: Dataset Response.]]<br />
<br />
<br />
suffix = <font size="2"><code>'''.iso'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .iso'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-metadata#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ISO Conformance Score Service ]] ====<br />
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 scores how well the metadata held in the [[DAP4: Responses#Dataset_Response | Dataset Response]] conforms to ISO 19115.<br />
<br />
<br />
suffix = <font size="2"><code>'''.rubric'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .rubric'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/iso-19115-score#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: NetCDF File-out Service ]] ====<br />
This service provides data responses in NetCDF-4 file format. When invoked the regular DAP data response will be repackaged as a NetCDF 4 file. <br />
<br />
suffix = <font size="2"><code>'''.nc4'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc4' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf-4'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: ASCII Data Service]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ascii'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.ascii' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/ascii#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: XML Data Service]] ====<br />
This service provides data responses in XML format. When invoked the constrained Dataset response document (DDX) will be marked up with the data values of the request and returned. Large requests may be denied.<br />
<br />
<br />
suffix = <font size="2"><code>'''.xdap'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.xdap' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/xml-data#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP4: Native File Access Service ]] ====<br />
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. Servers MAY elect to not support this response, for example, for generated data, very large data, et cetera.<br />
<br />
<br />
suffix = <font size="2"><code>'''.file'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .file'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/file#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: Type varies with file type.<br />
<br/><br />
<br />
==== [[DAP4: Server Version Service ]]====<br />
This service provides software versioning information. When invoked the service returns an XML file containing a description of the version of the server and it's components.<br />
<br />
<br />
suffix = <font size="2"><code>'''.ver'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ver'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/version#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
=== DAP2 Services ===<br />
<br />
In order to support legacy client applications DAP4 server implementations MAY support the DAP2 services stack. If they do so the DAP2 services MUST be organized as described in this section.<br />
<br />
<br />
<br />
==== [[DAP2: Data Service]]====<br />
The DAP2 data service provides DAP2 data access to the data resource.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dods'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dods' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dods#</nowiki>'''</code></font><br/><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/octet-stream'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDX Service ]]====<br />
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.<br />
<br />
suffix = <font size="2"><code>'''.ddx'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .ddx'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/ddx#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/xml'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DDS Service ]]====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.dds'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.dds' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/dds#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: DAS Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.das'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .das'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/das#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/plain'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: Info Service ]] ====<br />
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.<br />
<br />
<br />
suffix = <font size="2"><code>'''.info'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + .info'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap2/Info#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''text/html'''</code></font><br/><br />
<br/><br />
<br />
==== [[DAP2: NetCDF Service ]] ====<br />
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. <br />
<br />
suffix = <font size="2"><code>'''.nc'''</code></font><br/><br />
service url = <font size="2"><code>'''dataset_url + '.nc' + [?dap_constraint]'''</code></font><br/><br />
role id = <font size="2"><code>'''<nowiki>http://services.opendap.org/dap4/netcdf-3#</nowiki>'''</code></font><br/><br />
<br />
Default/primary media type: <font size="2"><code>'''application/x-netcdf'''</code></font><br/><br />
<br/><br />
<br />
<br />
[[Template: ServiceTemplate]]</div>EthanDavis