Closed jharmn closed 3 weeks ago
We extend this: http://datatracker.ietf.org/doc/draft-ietf-appsawg-http-problem/ and add a few additional fields.
Parent: #566 (pretty sure you wanted to do that, @jasonh-n-austin ;)).
@Shulamite in order to support different APIs, we'd have to keep the definition of the error object loosely coupled (i.e. just a reference to an error field which provides a unique index of the potential errors). Prescribing a specific API error standard would preclude any existing API that doesn't use http-problem from using OAS.
Agreed, being able to define error codes at a top level in swagger.yaml
would be extremely useful. Possibly in the definitions
?
One more here
It's useful but isn't it too much specific? I mean every API handles errors differently (even if there's the RFC7807). BTW: I ended add an x- structure to my company OpenAPI spec to describe errors beyond HTTP status
I don't really understand what the issue is, is it just to define the HTTP status message?
You define an error as a model object through paths/{url}/{verb}/response/{status_code},
like this
responses:
200:
description: Valid Response
schema:
$ref: "#/definitions/Response"
400:
description: Client input error
schema:
$ref: "#/definitions/ClientError"
default:
description: Client or server error
schema:
$ref: "#/definitions/Error"
and then in your definitions
Error:
required:
- status
- code
- message
properties:
status:
type: integer
code:
type: string
enum: [MISSING_REQUIRED_PARAMETER, INVALID_INPUT, OTHER]
message:
type: string
more_info:
type: string
Is this also to define a generic error set for all APIs, rather than having to do this at an individual request level?
Some news?
@tadhgpearson: Your example shows the current shortcoming: There is only one piece of information for each HTTP status code. Many HTTP status codes above 400 can have multiple reasons, each. These reasons cannot be properly documented today. What is needed is:
I definitely second the original request.
@jharmn This issue is marked with the "OpenAPI.Next Proposal" label. Does this mean it is being discussed for OpenAPI 3.1? If so, where does it stand?
Would like to chime-in here and understand whether there is an active proposal for error codes in the spec. We are currently using something similar on docs.microsoft.com, however that is done with the help of an extension rather than natively.
I would love to see this make an appearance in the spec. My company, and plenty of others it seems, use structured messages to provide error details. The HTTP status by itself can only convey the nature of the error in vague, high-level terms. It's up to the response body (or custom headers, if that's your cup of tea) to provide more granular information to the caller.
I think @andy-maier really nailed it in his summary. What is needed is a way to globally define how error details are communicated (such as header names or body structure), and list all of the possible values. Then, each response can indicate which of those errors are relevant.
This information could then be used in a number of ways throughout the OAS ecosystem:
RFC-7807 has been mentioned on a couple of occasions, here and in #1392. I agree that specification can be useful, but by itself it doesn't accomplish what's needed. For one thing, the RFC only defines the structure of an error response, and somewhat loosely at that. A huge component of this request is to be able to describe the contents of the error responses. Furthermore, there are plenty of APIs out there that were either created before the RFC, or in ignorance of it.
With the caveat that I'm rather new to OpenAPI, something like this would make sense to me:
errorDefinition: # or errorScheme?
headers:
- X-Error-Code
- X-Error-Message
# or...
responseBody:
schema:
type: object
properties:
code:
type: string
message:
type: string
# or
$ref: '#/components/schemas/Error'
identifier: ['code'] # Properties that are expected to be unique
errors:
badEmail: # arbitrary, unique name
code: '1234' # or X-Error-Code: ...
message: 'Invalid email address' # or X-Error-Message: ...
# ... and so on
# ...
paths:
/example:
get:
responses:
'400':
errors:
- $ref: '#/errorDefinition/errors/badEmail'
Would love to see this one in the next releases.
not sure that this should goes to OAS spec, as the OAS spec does not dictate any model of resource , pattern , can be REST , can be RPC like
here it is munch more a topic of modelization that the OAS spec so far does not touch
@MikeRalphson : what about closing this ticket and if ever it s something considered as usefull , merge all the request and keeping only one alive ? this one looks pretty the same https://github.com/OAI/OpenAPI-Specification/issues/1392
Closing this ticket as it pertains to error modeling. The OAS does not evaluate the quality of data or error models but provides tools for designers to create their models.
This concern could be addressed in an ‘API guidelines’ topic, which is not included here, as it is usually highly opinionated and debatable.
In providing quality documentation, it's necessary to provide more than "400 - Bad Request". Usually, an error object defines a key which indicates more specifically what was wrong (this applies to 5xx range as well), usually referred to as an 'error code' (not the HTTP status code). In addition, when testing for whether a given error is intended to be produced by a given operation, it's helpful to have the verb/uri/status correlated to a given 'error code'. At a minimum, all potential 'error codes' should be documented for a given API (realm of verbs+uri's+statuses). These 'error codes' could be numeric (e.g.
100100
) or strings (e.g.AUTHORIZATION_VOIDED
). The field/key they are mapped to could be variable, such ascode
,name
.Examples: https://developer.paypal.com/docs/api/#errors https://stripe.com/docs/api#errors
We store proprietary data to keep track of these correlations, at an API level (representing a group of verb/url/statuses):
It would be very helpful to have the ability to specify what the 'error code' field is in error responses, and to provide a list of these errors. Defining them at a
swagger.yaml
level is a minimum, and at an operation/status level would be the most granular (probably useful in testing precision).Perhaps in the spirit of #398, defining a global list of status codes would be useful, in addition to specific 'error codes'.