Designing an api - should we include 4xx responses or not in open api specification?

user_18652037 0
Viewed 206

While designing a GET endpoint I am confused ... Have designed Open API spec 3.0 for successful response ( 200 ) , invalid request ( missing mandatory stuff ) ( 400 )

Now I am confused about things like : 401 ( Unauthorized ) , 405 ( Method not allowed ) , 415 ( Unsupported Media type )

This API will need an api key to be provided in header and if not provided by user or an invalid api key is provided then they should get a 401 So I think I should be specifying 401 in my response spec . However when I look at swagger's Pet store ( https://editor.swagger.io/ ) they are not having this response code anywhere ... ?

My API spec ONLY supports GET with Content-type : application/json so I am thinking we dont need 405 ( DELETE / POST / PUT etc ) . Similarly if consumer sends application/xml or anything other than application/json we are not supporting it so this is why we should not be explicitly defining 415 in the spec ?

A bit confused which is why am looking into some inputs. Was referring to some pages here and here

swagger openapi
2 Answers

I think it is a good idea to document the Response Codes the API might return, it is indeed supported (but optional) by OpenAPI.
The consumers might find useful to know 401 Unauthorized means the JWT token is not supplied or it is expired, or 400 means the payload is incorrect (i.e. missing a specific attribute).

Check this example if you would like to see how Response Codes are documented and displayed by Swagger UI.

user_90955510

However when I look at swagger's Pet store they are not having this response code anywhere ... ?

The Pet Store is really just an example that one can use as a starting point or when you want to feed a tool with a sample spec. It is not meant to be normative. If you look through the sample code, you will even find paths which are RPC style (e.g. here) and other things that are not exactly RESTful.

why we should not be explicitly defining 415 in the spec ?

I think the blogposts that you found are helpful and do not contradict each other. Both of them rightfully recommend you to use the standard http response codes and provide a helpful error body. Some people omit response codes that they think are self-explanatory. But IMO, adding these few lines is totally worth it. If you add them diligently, then you get a key aspect of openapi right: The purpose of openapi is clarity and predictability of the capabilities and behaviour of your API.

So in summary: Yes, think about the responses that you are going to need, and do include these response codes in your api spec.

user_17466850
Related