Provide a means for defining erred responses

[nbibler]

Along the lines of #132, it would be useful to identify important or interesting error responses in a blueprint.

[zdne]

@nbibler Can you please elaborate a bit? The use case and perhaps a snippet of possible syntax would be great! Thanks

[MisinformedDNA]

I would think this refers to the error code they will receive. If a user passes in an invalid value, will they get a 400? 404?

Some examples from Spree Commerce:

Not Found

STATUS: 404 NOT FOUND
{
  "error": "The resource you were looking for could not be found."
}

Authorization Failure

STATUS: 401 UNAUTHORIZED
{
  "error": "You are not authorized to perform that action."
}

Invalid API Key

STATUS: 401 UNAUTHORIZED
{
  "error": "Invalid API key ([key]) specified."
}

They also return 422 when things can't process. Being able to include these in the documentation can be very helpful.

[pksunkara]

You can always write these in the description section of the API. Or do you want to add these when describing every action?

[pksunkara]

Here is an example api blueprint which adds the error descriptions and other stuff in API description section.

[zdne]

hey @MisinformedDNA

Would something like this work for you?

# API 

## Resource [/r]

### Retrieve [GET]

+ response 404

    Not Found

    + Body

            {
              "error": "The resource you were looking for could not be found."
            }

+ response 401

    Authorization Failure / Invalid API Key

    + Body

            {
              "error": "The resource you were looking for could not be found."
            }

[MisinformedDNA]

hey @zdne & @pksunkara ,

The resource model above looks like the start of something that might work, though I see you combined the 401 responses. It would be a shame if an API had to limit it's ability to return different error messages for a 401 response just because the documentation tool didn't support it. Obviously, the API could diverge, but that's not really the goal.

So we should be able to define certain requests that lead to certain error responses. So if the header is missing, the response should be able to give one error message. And if the parameter is the wrong type, a different error message and if the parameter leads to a resource that does not exist, another error. Similar to how we can specify different content-types and get different responses.

The goal is to be able to do testing with the docs, right? So we should want and be able to do negative testing as well.

I'm still very new here, so if I'm missing anything, I do apologize. But this looked like an interesting issue that I didn't see covered in the docs.

[itsjamie]

Would it not make sense to have this tied into the Trait #47 system in someway?

Such that if I apply the Trait "Protected" one possible response to the endpoint becomes the Authorization Failure response, if defined with the Trait.

[zdne]

I would say the solution to this would be #58 (#132) perhaps in combination with support for authentication #11

[zdne]

Please reopen if you think #58 / #132 / #11 are missing the point.