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.

Proposed Solution

Adopt the W3C HTTP/1.1 Status Code response

• Always show fully qualified response format (e.g. Atom) along with status code in response.
• For example, nominal cases show status code 200 for "OK. The request has succeeded."
• Do not show exception stack trace on error.

Custom error message handling

• Examples:
  • custom parameter in query is not recognized
  • no such dataset (different from zero granules found)
  • invalid date time entered
• Discussion needed: "4xx Client Errors" and "5xx Server Errors" alone are not as useful. For these cases, the response should still be well-formed (e.g. Atom). 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 generic, but only 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>

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>

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

May link to medium where proposal is openly discussed.

Consensus

Voting results.