0

The successful response of the API has a json format (based on an avro schema). For errors, should it define another format (schema) for exception? Or should the successful response include a section for errors? When an error happens, leave other sections empty and populate only errors.

This is more of an internal API and need to define various custom exception messages. Should it use the same HTTP STATUS CODE for all such application errors?

And how does these decisions affect OPEN API (SWAGGER)?

programmer
  • 249
  • 4
  • 12

1 Answers1

2

HTTP Status Codes belong to the general purpose transfer documents over a network domain.

In other words, your API should respond just like any other web site or web enabled document store.

The information that is specific to your domain belongs in the body of the response.

RFC 7807 defines application/problem+json, which is a general purpose schema for describing problems. You aren't required to use it, of course, but adopting a standardized schema does allow you to take advantage of work that has already been done in support of it.

For errors, should it define another format (schema) for exception? Or should the successful response include a section for errors?

Either of these can be reasonable, depending on what information you are trying to communicate.

Consider how you might do it on the web. I ask for an HTML representation of the status of my order, but there's been a delay with your supplier. Do you need to send me a completely different response? For a simple case like that, probably not - you aren't likely to have schema conflicts here, just various optional elements that depend on the state of the order.

On the other hand, you may need different expressions of information when a human is going to be required than in the case where you expect the information to be handled by machine.

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91