Conversation
invalid team IDThe team ID in your You can follow this guideline for help. |
tfrauenstein
left a comment
tfrauenstein
left a comment
There was a problem hiding this comment.
Thank you. I like the guideline improvement -- provides more details and clarity. However, I think we should avoid redundant and inconsistent change of the Problem Object specification -- see my comment.
|
@tfrauenstein @ePaul could you please have another look? |
| `application/problem+json` to provide an extensible human and machine readable | ||
| failure information beyond the HTTP response status code to transports the | ||
| failure kind (`type` / `title`) and the failure cause and location (`instant` / | ||
| `detail`). To make best use of this additional failure information, every | ||
| endpoints must be capable of returning a Problem JSON on client usage errors | ||
| ({4xx} status codes) as well as server side processing errors ({5xx} status | ||
| codes). |
There was a problem hiding this comment.
Let's keep this paragraph.
| of the extended failure information. | ||
| * Developers: to debug, diagnose and resolve issues during API integration or | ||
| operation | ||
| * Client applications: to inform users about errors (in user interface) and to |
There was a problem hiding this comment.
The problem object is provided for developers, not for application and UI users.
I would dismiss this and the above additions.
|
|
||
| *Note:* Problem `type` and `instance` identifiers in our APIs are not meant | ||
| to be resolved. {RFC-9457}[RFC 9457] encourages that problem types are URI | ||
| {RFC-9457}[RFC 9457] encourages that problem types are URI |
There was a problem hiding this comment.
The old wording is IMO clearer.
| The OpenAPI schema definition of the Problem JSON object can be found | ||
| https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml[on | ||
| GitHub]. You can reference it by using: | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| responses: | ||
| 503: | ||
| description: Service Unavailable | ||
| content: | ||
| "application/problem+json": | ||
| schema: | ||
| $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml#/Problem' | ||
| ---- | ||
|
|
There was a problem hiding this comment.
Should be moved to the Problem object Specification above.
| 4. For collections of related APIs, using shared type values for similar errors | ||
| and distinct values for different errors simplifies automated processing and | ||
| error handling for clients working across APIs. |
There was a problem hiding this comment.
This is not a hint for the clients, but for the servers is it?
It is unclear for me, and I not sure we should give this hint.
|
|
||
| CustomProblem: | ||
| allOf: | ||
| - $ref: "#/components/schemas/Problem" |
There was a problem hiding this comment.
Why not simply reference to the standard definition?
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>
|
@copilot check unresolved comments and address them in a new PR |
|
@ktsypkina I've opened a new pull request, #858, to work on those changes. Once the pull request is ready, I'll request review from you. |
|
|
||
| * A batch or bulk request *always* responds with HTTP status code {207} | ||
| unless a non-item-specific failure occurs. | ||
| unless a non-item-specific failure occurs. |
There was a problem hiding this comment.
Don't remove the leading spaces -- they are needed for formating
Incorporate API Guild thoughts on detailing Problem Object guidelines (#763)