DAP4: Asynchronous Request-Response Proposal - Revision history

Ndp: /* Examples */

2012-04-24T18:11:24Z

Examples

← Older revision		Revision as of 18:11, 24 April 2012
Line 106:		Line 106:

	Request:		Request:
	<pre>		<font size="2"><pre>
	GET /dap/path/data.nc?x,y,temp HTTP/1.1		GET /dap/path/data.nc?x,y,temp HTTP/1.1
	Host: server.org		Host: server.org
	Accept: application/vnd.opendap.org.dap4.data		Accept: application/vnd.opendap.org.dap4.data
	</pre>		</pre></font>

	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.		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.

	Response:		Response:
	<~~pre~~>		<font size="2"><source lang="xml">
	400 DAP Asynchronous Response Required		400 DAP Asynchronous Response Required
	DAP-Async-Required: true		DAP-Async-Required: true
Line 130:		Line 130:
	...		...
	</asynchronous>		</asynchronous>
	</~~pre~~>		</source></font>

	=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===		=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===

	Request:		Request:
	<pre>		<font size="2"><pre>
	GET /dap/path/data.nc?x,y,temp HTTP/1.1		GET /dap/path/data.nc?x,y,temp HTTP/1.1
	Host: server.org		Host: server.org
	DAP-Async-Accept: true		DAP-Async-Accept: true
	Accept: application/vnd.opendap.org.dap4.data		Accept: application/vnd.opendap.org.dap4.data
	</pre>		</pre></font>

	Response:		Response:
	<~~pre~~>		<font size="2"><source lang="xml">
	202 Accepted		202 Accepted
	Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8		Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8
Line 158:		Line 158:
	...		...
	</asynchronous>		</asynchronous>
	</~~pre~~>		</source></font>

	=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===		=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===

	Request:		Request:
	<pre>		<font size="2"><pre>
	GET /dap/path/data.nc?x,y,temp HTTP/1.1		GET /dap/path/data.nc?x,y,temp HTTP/1.1
	Host: server.org		Host: server.org
Line 169:		Line 169:
	DAP-Async-Accept-If-Expected-Delay-Less-Than: 60000		DAP-Async-Accept-If-Expected-Delay-Less-Than: 60000
	Accept: application/vnd.opendap.org.dap4.data		Accept: application/vnd.opendap.org.dap4.data
	</pre>		</pre></font>

	Response:		Response:
	<~~pre~~>		<font size="2"><source lang="xml">
	412 Precondition Failed		412 Precondition Failed
	Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8		Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8
Line 180:		Line 180:
	...		...
	</asynchronous>		</asynchronous>
	</~~pre~~>		</source></font>

	=== Constrained Data Request-Response using POST ===		=== Constrained Data Request-Response using POST ===

	Request:		Request:
	<pre>		<font size="2"><pre>
	POST /dap/path/data.nc HTTP/1.1		POST /dap/path/data.nc HTTP/1.1
	Host: server.org		Host: server.org
Line 192:		Line 192:

	<constraintExp>...</constraintExp>		<constraintExp>...</constraintExp>
	</pre>		</pre></font>

	Response:		Response:
	<~~pre~~>		<font size="2"><source lang="xml">
	202 Accepted		202 Accepted
	Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8		Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8
Line 211:		Line 211:
	...		...
	</asynchronous>		</asynchronous>
	</~~pre~~>		</source></font>

	=== Support notification of completion ===		=== Support notification of completion ===

	Request:		Request:
	<pre>		<font size="2"><pre>
	</pre>		</pre></font>

	Response:		Response:
	<pre>		<font size="2"><pre>
	</pre>		</pre></font>

EthanDavis: /* Proposed solution */

2012-04-24T16:49:26Z

Proposed solution

← Older revision		Revision as of 16:49, 24 April 2012
Line 29:		Line 29:
	Uses link relationships and media types described in the [[DAP4: Capabilities and Versioning]] Proposal.		Uses link relationships and media types described in the [[DAP4: Capabilities and Versioning]] Proposal.

	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 with a '''[[#400 DAP Asynchronous Response Required]]''' HTTP response code and inclusion of the '''[[#DAP Asynchronous Response Required\|DAP-Async-Required]]''' HTTP response header. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types\|below]]. A client can indicate willingness to accept asynchronous responses by including the '''[[#Accept DAP Asynchronous Response\|DAP-Async-Accept]]''' HTTP header.		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 with a '''[[#400 DAP Asynchronous Response Required\|400 DAP Asynchronous Response Required]]''' HTTP response code and inclusion of the '''[[#DAP Asynchronous Response Required\|DAP-Async-Required]]''' HTTP response header. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types\|below]]. A client can indicate willingness to accept asynchronous responses by including the '''[[#Accept DAP Asynchronous Response\|DAP-Async-Accept]]''' HTTP header.

	Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait with a '''[[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|DAP-Async-Accept-If-Expected-Delay-Less-Than]]''' HTTP header with a value given in milliseconds.		Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait with a '''[[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|DAP-Async-Accept-If-Expected-Delay-Less-Than]]''' HTTP header with a value given in milliseconds.
Line 39:		Line 39:
	'''DAP-Async-Required'''		'''DAP-Async-Required'''

	The '''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 DAP Asynchronous Response Required]] HTTP response code.		The '''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 DAP Asynchronous Response Required\|400 DAP Asynchronous Response Required]] HTTP response code.

	=== HTTP Request Headers ===		=== HTTP Request Headers ===

EthanDavis: /* Examples */

2012-04-24T16:47:19Z

Examples

← Older revision		Revision as of 16:47, 24 April 2012
Line 103:		Line 103:
	== Examples ==		== Examples ==

	=== GET ~~data~~ ===		=== Constrained Data Request-Response using GET ===

	Request:		Request:
Line 132:		Line 132:
	</pre>		</pre>

	=== ~~GET data~~ with DAP-Async-Accept Request Header ===		=== Constrained Data Request-Response with DAP-Async-Accept Request Header ===

	Request:		Request:
Line 160:		Line 160:
	</pre>		</pre>

	=== ~~GET data~~ with conditional DAP-Async-Accept Request Headers ===		=== Constrained Data Request-Response with conditional DAP-Async-Accept Request Headers ===

	Request:		Request:
Line 182:		Line 182:
	</pre>		</pre>

	=== POST ===		=== Constrained Data Request-Response using POST ===

	Request:		Request:

EthanDavis: /* Examples */

2012-04-24T16:41:58Z

Examples

← Older revision		Revision as of 16:41, 24 April 2012
Line 131:		Line 131:
	</asynchronous>		</asynchronous>
	</pre>		</pre>

	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 somewhat 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.

	An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.

	=== GET data with DAP-Async-Accept Request Header ===		=== GET data with DAP-Async-Accept Request Header ===

EthanDavis: /* 400 DAP Asynchronous Response Required */

2012-04-24T16:40:30Z

400 DAP Asynchronous Response Required

← Older revision		Revision as of 16:40, 24 April 2012
Line 67:		Line 67:
	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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).		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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).

	'''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 ~~somewhat~~ 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.		'''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.

	An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.		An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.

EthanDavis: /* 400 DAP Asynchronous Response Required */

2012-04-24T16:39:28Z

400 DAP Asynchronous Response Required

← Older revision		Revision as of 16:39, 24 April 2012
Line 67:		Line 67:
	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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).		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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).

	~~<blockquote>~~
	'''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 somewhat 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.		'''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 somewhat 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.

	An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.		An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.
	~~</blockquote>~~

	==== 412 Precondition Failed====		==== 412 Precondition Failed====

EthanDavis: /* 400 DAP Asynchronous Response Required */

2012-04-24T16:35:59Z

400 DAP Asynchronous Response Required

← Older revision		Revision as of 16:35, 24 April 2012
Line 66:		Line 66:

	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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).		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 '''DAP-Async-Required''' HTTP response header is also included in the response (see [[#Accept DAP Asynchronous Response\|above]]).

			<blockquote>
			'''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 somewhat 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.

			An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.
			</blockquote>

	==== 412 Precondition Failed====		==== 412 Precondition Failed====

EthanDavis: /* Examples */

2012-04-24T15:49:08Z

Examples

← Older revision		Revision as of 15:49, 24 April 2012
Line 99:		Line 99:
	== Examples ==		== Examples ==

	=== GET data ~~without DAP-Async-Accept Request Header~~ ===		=== GET data ===

	Request:		Request:
Line 107:		Line 107:
	Accept: application/vnd.opendap.org.dap4.data		Accept: application/vnd.opendap.org.dap4.data
	</pre>		</pre>

			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.

	Response:		Response:
Line 125:		Line 127:
	</asynchronous>		</asynchronous>
	</pre>		</pre>

			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 somewhat 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.

			An alternative would be to use a non-standard 4xx HTTP response code (e.g., we could choose 473). Clients should interpret any 4xx code that they do not recognize as a 400. However, this may not be handled well by all clients.

	=== GET data with DAP-Async-Accept Request Header ===		=== GET data with DAP-Async-Accept Request Header ===

EthanDavis at 15:46, 24 April 2012

2012-04-24T15:46:18Z

← Older revision		Revision as of 15:46, 24 April 2012
Line 96:		Line 96:

	== Discussion ==		== Discussion ==

			== Examples ==

			=== GET data without DAP-Async-Accept Request Header ===

			Request:
			<pre>
			GET /dap/path/data.nc?x,y,temp HTTP/1.1
			Host: server.org
			Accept: application/vnd.opendap.org.dap4.data
			</pre>

			Response:
			<pre>
			400 DAP Asynchronous Response Required
			DAP-Async-Required: true
			Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8

			<asynchronous>
			<expectedDelay millisec="600000" />
			<notificationSupport>
			<polling frequencyLimitInMillisecs="60000" />
			<email />
			<longConnect />
			<http />
			</notificationSupport>
			...
			</asynchronous>
			</pre>

			=== GET data with DAP-Async-Accept Request Header ===

			Request:
			<pre>
			GET /dap/path/data.nc?x,y,temp HTTP/1.1
			Host: server.org
			DAP-Async-Accept: true
			Accept: application/vnd.opendap.org.dap4.data
			</pre>

			Response:
			<pre>
			202 Accepted
			Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8

			<asynchronous>
			<expectedDelay millisec="600000" /> <!-- Estimated delay of 10 minutes. -->
			<notificationSupport>
			<polling frequencyLimitInMillisecs="60000" /> <!-- Don't poll more often than every minute. -->
			</notificationSupport>
			<status value="accepted"
			rel="http://opendap.org/rel/dap/asynch/status"
			type="application/vnd.opendap.org.dap.asynchronous+xml"
			href="http://server.org/dap/path/data.nc-ABCD.status" />
			...
			</asynchronous>
			</pre>

			=== GET data with conditional DAP-Async-Accept Request Headers ===

			Request:
			<pre>
			GET /dap/path/data.nc?x,y,temp HTTP/1.1
			Host: server.org
			DAP-Async-Accept: true
			DAP-Async-Accept-If-Expected-Delay-Less-Than: 60000
			Accept: application/vnd.opendap.org.dap4.data
			</pre>

			Response:
			<pre>
			412 Precondition Failed
			Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8

			<asynchronous>
			<expectedDelay millisec="600000" /> <!-- Greater than that specified in DAP-Async-Accept-If-Expected-Delay-Less-Than header. -->
			...
			</asynchronous>
			</pre>

			=== POST ===

			Request:
			<pre>
			POST /dap/path/data.nc HTTP/1.1
			Host: server.org
			DAP-Async-Accept: true
			Content-Type: application/vnd.opendap.org.dap4.ce+xml;charset=UTF-8

			<constraintExp>...</constraintExp>
			</pre>

			Response:
			<pre>
			202 Accepted
			Content-Type: application/vnd.opendap.org.dap.asynchronous+xml;charset=UTF-8

			<asynchronous>
			<expectedDelay millisec="600000" /> <!-- Estimated delay of 10 minutes. -->
			<notificationSupport>
			<polling frequencyLimitInMillisecs="60000" /> <!-- Don't poll more often than every minute. -->
			</notificationSupport>
			<status value="accepted"
			rel="self
			http://opendap.org/rel/dap/asynchronous"
			type="application/vnd.opendap.org.dap.asynchronous+xml"
			href="http://server.org/dap/path/data.nc-ABCD.status" />
			...
			</asynchronous>
			</pre>

			=== Support notification of completion ===

			Request:
			<pre>
			</pre>

			Response:
			<pre>
			</pre>

EthanDavis at 15:36, 24 April 2012

2012-04-24T15:36:02Z

← Older revision		Revision as of 15:36, 24 April 2012
Line 29:		Line 29:
	Uses link relationships and media types described in the [[DAP4: Capabilities and Versioning]] Proposal.		Uses link relationships and media types described in the [[DAP4: Capabilities and Versioning]] Proposal.

	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 with a '''[[#400 DAP Asynchronous Response Required]]''' HTTP response code and inclusion of the '''[[#DAP Asynchronous Response Required\|DAP-Async-Required]]''' HTTP response header. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types~~: Asynchronous Information~~\|below]]. A client can indicate willingness to accept asynchronous responses by including the '''[[#Accept DAP Asynchronous Response\|DAP-Async-Accept]]''' HTTP header.		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 with a '''[[#400 DAP Asynchronous Response Required]]''' HTTP response code and inclusion of the '''[[#DAP Asynchronous Response Required\|DAP-Async-Required]]''' HTTP response header. The response body must contain a document in one of the asynchronous information media types listed [[#Media Types\|below]]. A client can indicate willingness to accept asynchronous responses by including the '''[[#Accept DAP Asynchronous Response\|DAP-Async-Accept]]''' HTTP header.

	Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait with a '''[[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|DAP-Async-Accept-If-Expected-Delay-Less-Than]]''' HTTP header with a value given in milliseconds.		Clients can make conditional requests for asynchronous responses by indicating the maximum time they are willing to wait with a '''[[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|DAP-Async-Accept-If-Expected-Delay-Less-Than]]''' HTTP header with a value given in milliseconds.
Line 47:		Line 47:
	'''DAP-Async-Accept'''		'''DAP-Async-Accept'''

	A client indicates willingness to accept asynchronous responses by including the '''DAP-Async-Accept''' HTTP header. The value of the header must be one of the asynchronous resource media types listed [[#Media Types~~: Asynchronous Information~~\|below]].		A client indicates willingness to accept asynchronous responses by including the '''DAP-Async-Accept''' HTTP header. The value of the header must be one of the asynchronous resource media types listed [[#Media Types\|below]].

	==== Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion ====		==== Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion ====
Line 59:		Line 59:
	==== 202 Accepted ====		==== 202 Accepted ====

	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~~: Asynchronous Information~~\|below]].		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]].

	==== 400 DAP Asynchronous Response Required ====		==== 400 DAP Asynchronous Response Required ====
Line 71:		Line 71:
	The '''412 Precondition Failed''' HTTP response code is used to indicate that the DAP request has been rejected because it did not meet the '''DAP-Async-Accept-If-Expected-Delay-Less-Than''' condition (see [[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|above]]) that was specified in the request.		The '''412 Precondition Failed''' HTTP response code is used to indicate that the DAP request has been rejected because it did not meet the '''DAP-Async-Accept-If-Expected-Delay-Less-Than''' condition (see [[#Accept DAP Asynchronous Response Conditionally on Estimated Time to Completion\|above]]) that was specified in the request.

	=== Media Types~~: Asynchronous Information~~ ===		=== Media Types ===

	Information about an asynchronous response can be represented in one of the following media types:		Information about an asynchronous response can be represented in one of the following media types:
Line 87:		Line 87:
	* The protobuf representation is a document following the definition given here (???).		* The protobuf representation is a document following the definition given here (???).

	=== Link Relationships~~: Asynchronous Information~~ ===		=== Link Relationships ===

	'''<nowiki>http://opendap.org/rel/dap/asynchronous</nowiki>'''		'''<nowiki>http://opendap.org/rel/dap/asynchronous</nowiki>'''

	The URL of a link with this relation can be used to GET an asynchronous information resource. The representation received will be a document in one of the asynchronous information media types listed [[#Media Types~~: Asynchronous Information~~\|above]].		The URL of a link with this relation can be used to GET an asynchronous information resource. The representation received will be a document in one of the asynchronous information media types listed [[#Media Types\|above]].

	== Rationale for the solution ==		== Rationale for the solution ==

	== Discussion ==		== Discussion ==