RE: Call for consensus on documenting how "errors" can be given an identifier and be reused (ISSUE-39)

On 16 Jul 2014 at 20:27, Tomasz Pluskiewicz wrote:
> I think it will make sense if the identifier was communicated to the
> client in response header or body.
> 
> By doing so the server could communicate various errors for a single
> HTTP status code. For example status code 403 could be returned for
> numerous reasons in an API but giving the possible statuses
> identifiers doesn't help the client understand why a particular
> request failed.

Yeah, that's the idea. You would return the same Status (StatusCodeDescription)/Error that has been communicated as possibleStatus beforehand. I'm still a bit on the fence whether such a Status should be an instance of a possibleStatus (making it a class)

  {
    "@type": "/api-doc/QuotaExceeded",
    "description": "You made more requests than allowed. Wait for 5 minutes"
  }

or the possibleStatus itself

  {
    "@id": "/api-doc/RequestQuotaExceeded",
    "title": "Request Quota Exceeded"
  }

I find the former slightly better. Strictly speaking, the later doesn't allow to, e.g., tailor the description to concrete request. Also logging the error server and client side is made more difficult at it doesn't have a unique identifier (the first case may have one, in the example it doesn't however).


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 21 July 2014 18:50:29 UTC