search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.64k stars 2.14k forks source link

System wide responses #300

Open alexpanov opened 8 years ago

alexpanov commented 8 years ago

Hi all,

Excuse me if this is a duplicate, I was unable to find a similar issue.

I would like to be able to specify system-wide responses. Under certain conditions my API will respond with a response that will be returned only under said conditions. This response will always have the same status code and JSON schema.

As far as I can read the Spec, it is not currently possible. Please correct me if I'm wrong. I think it would certainly be useful to have such a feature.

zdne commented 8 years ago

As far as I can read the Spec, it is not currently possible. Please correct me if I'm wrong. I think it would certainly be useful to have such a feature.

This is correct. There is no such a feature at the moment.

We are considering using "global" responses for authentication as proposed in the API Blueprint RFC 0002: Authentication Framework.

Would you care elaborate on other examples? Are they based on protocol (HTTP) status codes?

Note with the introduction of data structures you are now able to define (and reuse) shared data structures (such as errors). While they are not HTTP responses (payloads) they can carry the most important part – data definition and semantics.

alexpanov commented 8 years ago

@zdne Thank you for your response.

Yes, this is pretty much what I am talking about. We did not go for HTTP 403 just yet, but HTTP 402 instead. We did not want to overload the HTTP 403 because users may not have certain permissions and it fits our app pretty well as far as we see it now.

Do you have any idea when the RFC makes it into a release?

zdne commented 8 years ago

Do you have any idea when the RFC makes it into a release?

The current roadmap is here https://github.com/apiaryio/api-blueprint/wiki/Roadmap#features .. it is number 4 so I would not expect it anytime soon.

zdne commented 8 years ago

But any contribution is highly appreciated!

zdne commented 8 years ago

As for documenting error responses. I suggest to document the data structure and mention in in the API overview section. Check https://developers.csas.cz/html/devs/net-banking.html#/introduction/allowed-https-requests: for some inspiration

zdne commented 8 years ago

If you would like to contribute or have an idea how to describe error responses in general please feel free to suggest it here or as an RFC. Thanks!

vassilevsky commented 8 years ago

Hello 👻 I come from StackOverflow 🙃

http://stackoverflow.com/q/37243264

Would be cool to be able to specify response media type once and for all.

zdne commented 8 years ago

I like the idea. Question is, do we need an opt-out if you, for some reason, do not want to specify the media type for a particular request?

pksunkara commented 8 years ago

The "not wanting to specify any media type for a particular request" can be a bit tricky if we support global media types.