search

zalando / restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
https://opensource.zalando.com/restful-api-guidelines/
Creative Commons Attribution 4.0 International
2.65k stars 390 forks source link

Examples for good problem types #550

Closed whiskeysierra closed 4 years ago

whiskeysierra commented 4 years ago

In Rule 176 we advocate for application/problem+json but we don't give good examples and guidance for:

While the RFC encourages a URI reference that can be dereferenced:

This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]).

https://tools.ietf.org/html/rfc7807#page-5

I'd suggest to pick non-URL types, e.g. my-custom-problem-type. It frees us from situation where locations URLs change and one would need to server a proper HTML page there. We have OpenAPI for that, imho.

ePaul commented 4 years ago

Sounds good. Do you (@whiskeysierra) want to work on this?

whiskeysierra commented 4 years ago

Yes, I will.

On Tue, 3 Dec 2019, 15:25 Paŭlo Ebermann, notifications@github.com wrote:

Sounds good. Do you (@whiskeysierra https://github.com/whiskeysierra) want to work on this?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/zalando/restful-api-guidelines/issues/550?email_source=notifications&email_token=AADI7HNWSA6SOS66WV3DRADQWZT4BA5CNFSM4JPP4AT2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEFZRK2I#issuecomment-561190249, or unsubscribe https://github.com/notifications/unsubscribe-auth/AADI7HNRKWL7R2PZQF67OTDQWZT4BANCNFSM4JPP4ATQ .