A guideline for errors
Errors are a crucial part of the developer experience when using an API. As developers learn the API they inevitably run into errors. The quality and consistency of the error messages returned to them will play a large part in how quickly they can learn the API, how they can be more effective with the API, and how much they enjoy using the API. We need consistency across all services for the error format returned in the response body. Change-Id: Iae6dc4d84c11c95a97d2451668ebffa80c9821ec
This commit is contained in:
Everett Toews
parent
d2230489dc
commit
b0e3c5cec8
|
|
@ -0,0 +1,30 @@
|
|||
{
|
||||
"errors": [
|
||||
{
|
||||
"request_id": "1dc92f06-8ede-4fb4-8921-b507601fb59d",
|
||||
"code": "orchestration.create-failed",
|
||||
"status": 418,
|
||||
"title": "The Stack could not be created",
|
||||
"detail": "The Stack could not be created because of error(s) in other parts of the system.",
|
||||
"links": [
|
||||
{
|
||||
"rel": "help",
|
||||
"href": "TODO(sdague): example href"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"request_id": "d413ea12-dfcd-4009-8fad-229b475709f2",
|
||||
"code": "compute.scheduler.no-valid-host-found",
|
||||
"status": 403,
|
||||
"title": "No valid host found",
|
||||
"detail": "No valid host found for flavor m1.xlarge.",
|
||||
"links": [
|
||||
{
|
||||
"rel": "help",
|
||||
"href": "TODO(sdague): example href"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
{
|
||||
"$schema": "http://json-schema.org/draft-04/schema#",
|
||||
"id": "http://specs.openstack.org/openstack/api-wg/errors-schema.json#",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"errors": {
|
||||
"type": "array",
|
||||
"description": "An ordered list of errors with the most recent error first.",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"description": "Additional information about problems encountered while performing an operation.",
|
||||
"properties": {
|
||||
"request_id": {
|
||||
"type": "string",
|
||||
"description": "A unique identifier for this particular occurrence of the problem. If this property is present, it MUST match the X-Openstack-Request-Id header of the response in which it occurred."
|
||||
},
|
||||
"code": {
|
||||
"type": "string",
|
||||
"description": "A service-specific error code. The general form of the code is service-name.error-code. service-name MUST be the service name as defined by the service field of https://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml where spaces within the service name are replaced by '-' and if the word 'service' appears in the name, it MUST be omitted. error-code is defined by service project team and MUST only consist of lowercase alpha, numeric, '.', and '-' characters."
|
||||
},
|
||||
"status": {
|
||||
"type": "integer",
|
||||
"description": "The HTTP status code applicable to this problem. It MUST match the status code of the response in which it occurred."
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "A short, human-readable summary of the problem. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization."
|
||||
},
|
||||
"detail": {
|
||||
"type": "string",
|
||||
"description": "A human-readable explanation specific to this occurrence of the problem."
|
||||
},
|
||||
"links": {
|
||||
"type": "array",
|
||||
"description": "An array that MUST contain at least one Link Description Object with a 'rel': 'help' and an 'href' that links to a resource that can help the user as defined by http://specs.openstack.org/openstack/api-wg/guidelines/errors.html#errors-documentation",
|
||||
"minItems": 1,
|
||||
"items": { "$ref": "http://json-schema.org/draft-04/links" }
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"status",
|
||||
"title",
|
||||
"detail",
|
||||
"links"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"errors"
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
Errors
|
||||
======
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
Errors are a crucial part of the developer experience when using an API. As
|
||||
developers learn the API they inevitably run into errors. The quality and
|
||||
consistency of the error messages returned to them will play a large part
|
||||
in how quickly they can learn the API, how they can be more effective with
|
||||
the API, and how much they enjoy using the API.
|
||||
|
||||
Errors JSON Schema
|
||||
------------------
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
|
||||
document are to be interpreted as described in :rfc:`2119`.
|
||||
|
||||
.. literalinclude:: errors-schema.json
|
||||
:language: json
|
||||
|
||||
Errors JSON Example
|
||||
-------------------
|
||||
|
||||
.. literalinclude:: errors-example.json
|
||||
:language: json
|
||||
|
||||
.. note:: This example is completely contrived. This is not how Orchestration
|
||||
or Compute responds with errors. It merely illustrates how a service might
|
||||
chain together errors.
|
||||
|
||||
Errors Documentation
|
||||
--------------------
|
||||
|
||||
TODO(sdague): Expand on the vision behind Errors Documentation
|
||||
Loading…
Reference in New Issue