Discovery Change Proposal-7

<< Back to the Discovery Change Proposals page

DCP-7: Error Handling Best Practices for Discovery Repsonse

• Progress (fill in the dates as the process moves forward)

1. Submitted on: 2012-02-14
2. Review period: TBD
3. Revision: TBD
4. Vote: TBD
5. Final review: TBD
6. Ratified: TBD
7. 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 W3C HTTP/1.1 Status Code response

• Best practices
  • Always show fully qualified response format (e.g. Atom) along with status code in response.
  • Do not show exception stack trace on error.
• HTTP response codes
  • 4xx covers client-side issues
  • 5xx covers server-side issues
  • Nominal status codes for Discovery use cases:

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. unrecognized parameter name.
401	Unauthorized	Authentication is required for this feed, but not provided.
403	Forbidden	Valid request, but feed is restricted.	Explain why the request was rejected.
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.	Explain the upstream issue.
503	Service Unavailable	The services are temporarily unavailable.	Should explain cause of unavailability. e.g. 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 can be used to describe no results were found.
• An Atom example response with zero results.

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

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-type: text/xml

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

Content-type: text/plain

An unsupported OpenSearch search field "foobar" was specified.

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.

Discussions

Custom error message handling

• Should the response always be well-formed (e.g. Atom)? Or should we allow arbitrary error messages in mime-types such as plain/text?
• 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.
    • Need some tag that is not in <entry> tag for carrying human-readable error message
    • <content> tag is more versatile, but only allowed in <entry> tag:

<content type="application/xhtml+xml" xml:lang="en">
  <div class="article" xmlns="http://www.w3.org/1999/xhtml">
   My arbitrary message.
  </div>
</content>

Consensus

TBD after voting.