Difference between revisions of "Discovery Change Proposal-7"
Line 32: | Line 32: | ||
* Best practices | * Best practices | ||
− | ** Always show fully qualified response format ( | + | ** Always show fully qualified response format (with corresponding content-type) along with status code in response. |
** Do not show exception stack trace on error. | ** 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 | * HTTP response codes | ||
** 4xx covers client-side issues | ** 4xx covers client-side issues | ||
** 5xx covers server-side issues | ** 5xx covers server-side issues | ||
− | ** Nominal status codes for Discovery use cases: | + | ** Nominal status codes relevant for Discovery use cases: |
{| class="wikitable" | {| class="wikitable" | ||
Line 54: | Line 58: | ||
|Bad Request | |Bad Request | ||
|Bad syntax in request string. | |Bad syntax in request string. | ||
− | |Explain why the request string was bad. e.g. unrecognized parameter | + | |Explain why the request string was bad. e.g. an invalid OpenSearch request with unrecognized parameter field(s). |
|- | |- | ||
|401 | |401 | ||
Line 64: | Line 68: | ||
|Forbidden | |Forbidden | ||
|Valid request, but feed is restricted. | |Valid request, but feed is restricted. | ||
− | | | + | |(for security reasons, might not want to explain reason why) |
|- | |- | ||
|404 | |404 | ||
Line 73: | Line 77: | ||
|500 | |500 | ||
|Internal Server Error | |Internal Server Error | ||
− | |Fallback error message. | + | |Fallback error message. This is not expected. Needs to be reported. |
− | + | | | |
|- | |- | ||
|502 | |502 | ||
|Bad Gateway | |Bad Gateway | ||
|Server received invalid response upstream. | |Server received invalid response upstream. | ||
− | | | + | |(for security reasons, might not want to explain reason why) |
|- | |- | ||
|503 | |503 | ||
|Service Unavailable | |Service Unavailable | ||
|The services are temporarily unavailable. | |The services are temporarily unavailable. | ||
− | |Should explain cause of unavailability. e.g. unable to reach backend database. | + | |Should explain cause of unavailability. e.g. too many requests. unable to reach backend database. |
|} | |} | ||
Line 90: | Line 94: | ||
* Response shall contain a valid response with no item entries. Do not show error in response. | * 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 <opensearch:totalResults> tag should always indicate the number of results, where for this case be equal to 0. |
− | * The subtitle tag | + | * 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. | * An Atom example response with zero results. | ||
<pre> | <pre> | ||
Line 116: | Line 121: | ||
* Do not return stack trace from server. | * Do not return stack trace from server. | ||
* Discovery services shall provide a well-formed error message with appropriate content-type. | * Discovery services shall provide a well-formed error message with appropriate content-type. | ||
+ | * Examples: | ||
Content-type: text/xml | Content-type: text/xml | ||
Line 129: | Line 135: | ||
An unsupported OpenSearch search field "foobar" was specified. | An unsupported OpenSearch search field "foobar" was specified. | ||
</pre> | </pre> | ||
− | |||
== Rationale for the Solution == | == Rationale for the Solution == | ||
Line 136: | Line 141: | ||
== Discussions == | == 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 === | === Custom error message handling === | ||
− | * Should the response always be well-formed | + | * 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? | * 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. | ** 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 == | == Consensus == | ||
TBD after voting. | TBD after voting. |
Revision as of 15:49, March 13, 2012
<< 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)
- 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 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.
- 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.
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.