View source for Discovery Change Proposal-7

[[Discovery_Change_Proposals|<< Back to the Discovery Change Proposals page]]


= DCP-7: Error Handling Best Practices for Discovery Response =

* '''Progress''' (fill in the dates as the process moves forward)
# '''Submitted on''': 2012-02-14
# '''Review period''': TBD
# '''Revision''': TBD
# '''Vote''': TBD
# '''Final review''': TBD
# '''Ratified''': TBD
# '''Rejected''': TBD
* '''Facilitator''': Hook Hua

== Description ==

Current implementations of ESIP Discovery services (OpenSearch, DataCast, and ServiceCast) have varying error handling behavior in the http response. Since these micro-standards mostly refer the request/response format, little has been said about the response format when an error is encountered.

== Problem Addressed ==

There is little interoperability in error response handling of these services. We want to promote a consistent approach to handling errors.

Use case examples for error handling:
* A request with a custom parameter that is not recognized.
* An OpenSearch request for a dataset that does not exist. This case is different from granule-level search with 0 results.
* A request with an invalid date time entered.

== Proposed Solution ==

=== Adopt the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html W3C HTTP/1.1 Status Code] response ===

* Best practices
** Always show fully qualified response format (with corresponding content-type) along with status code in response.
** Do not show exception stack trace on error.
** for OpenSearch requests with invalid request parameters
*** return 400 Bad Request with appropriate error message. 
*** do not return successfully and rely on OpenSearch <Query> element to repeat the valid parameters.
*** users need to know if any of their request parameters are not used in the constraint search.
* HTTP response codes
** 4xx covers client-side issues
** 5xx covers server-side issues 
** Nominal status codes relevant for Discovery use cases:

{| class="wikitable"
|-
! Code
! Status
! Description
! Error Message
|-
|200
|OK
|Standard response for successful HTTP requests.
|
|-
|400
|Bad Request
|Bad syntax in request string.
|Explain why the request string was bad. e.g. an invalid OpenSearch request with unrecognized parameter field(s).
|-
|401
|Unauthorized
|Authentication is required for this feed, but not provided.
|
|-
|403
|Forbidden
|Valid request, but feed is restricted.
|(for security reasons, might not want to explain reason why) 
|-
|404
|Not Found
|Invalid URI request.
|
|-
|500
|Internal Server Error
|Fallback error message. This is not expected. Needs to be reported.
|
|-
|502
|Bad Gateway
|Server received invalid response upstream.
|(for security reasons, might not want to explain reason why) 
|-
|503
|Service Unavailable
|The services are temporarily unavailable.
|Should explain cause of unavailability. e.g. too many requests. unable to reach backend database.
|}

=== Handling zero results ===

* Response shall contain a valid response with no item entries. Do not show error in response.
* The <opensearch:totalResults> tag should always indicate the number of results, where for this case be equal to 0.
* The <subtitle> tag should provide a user-friendly message indicating that no results were found.
** Many mass-market Atom readers show the <subtitle> value along side the result feed list and is easily seen.
* An Atom example response with zero results.
<pre>
 <?xml version="1.0" encoding="UTF-8"?>
  <feed xmlns="http://www.w3.org/2005/Atom" 
          xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
          xmlns:georss="http://www.georss.org/georss">
      <title>Granules</title>
      <subtitle>No results found for "temperature".<subtitle>
      <updated>2012-02-14T18:30:02Z</updated>
      <author>
        <name>A Data Center</name>
      </author>
      <id>urn:uuid:00000000-0000-0000-0000000000</id>
      <opensearch:totalResults>0</opensearch:totalResults>
      <opensearch:startIndex>0</opensearch:startIndex>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
  </feed>
</pre>

=== Custom error message handling ===

* For "4xx Client Errors" and "5xx Server Errors", the response error handling is not consistently defined.
* Do not return stack trace from server.
* Discovery services shall provide a well-formed error message with appropriate content-type.
* Content-types shall be a displayable type to facilitate light-weight clients that can show the error messages to the user.
** e.g. content-type: text/plain, text/xml with xsl, text/html.
* Examples:

Content-type: text/xml
<pre>
 <?xml version="1.0" encoding="UTF-8"?>
 <errors>
   <error>An unsupported OpenSearch search field "foobar" was specified.</error>
 </errors>
</pre>

Content-type: text/plain
<pre>
An unsupported OpenSearch search field "foobar" was specified.
</pre>

== Rationale for the Solution ==

We want to ensure backwards compatibility with "mass-market" feed readers, while also promoting best practices for a set of conventions of how the existing standards are use. Where possible, error handling should be easy to implement to promote simple and light-weight clients.

== Discussions ==

===  W3C HTTP/1.1 Status Code ===

* 403 Forbidden: for security reasons, might not want to explain the reason why.
* 502 Bad Gateway: for security reasons, might not want to explain the reason why.

=== Custom error message handling ===

* Should the response always be well-formed? Or should we allow arbitrary error messages in mime-types such as plain/text?
** from [[Discovery_Telecon_2012-03-13 | 2012-03-13 telecon]], we decided to always have well-formed response with mime-type, but do not use Atom responses for bad requests. 
* How best to convey more machine-readable error message while being backwards compatible with mass-market readers?
** Atom 1.0 has no built-in tags to convey this.
* OpenSearch with invalid request parameters
** return 400 Bad Request with appropriate error message. 
** do not return successfully and rely on OpenSearch <Query> element to repeat the valid parameters.
** users need to know if any of their request parameters are not used in the constraint search.

== Consensus ==

TBD after voting.