Discovery Change Proposal-7

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

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 (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:

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.

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

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