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.
| the member MUST be ignored -- i.e., processing will continue as if | ||
| the member had not been present. | ||
|
|
||
| ===== status (integer) |
There was a problem hiding this comment.
I think we should avoid specification of the problem object in the GUI guideline redundantly (and possibly inconsistently) to the open-source specification in https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml
Instead we should clearly refer to it and update it as part of the PR, if helpful.
It also allows us to better understand the differences.
There was a problem hiding this comment.
I agree that we should avoid redundancies, but having it written out in the guidelines makes it easier to read than just pointing to the file. Not sure what the best way of doing this is, though.
|
@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.
| support automated processing and error handling when appropriate. | ||
|
|
||
| The OpenAPI schema definition of the Problem JSON object can be found | ||
| ==== Problem schema members, supported by the API guidelines |
There was a problem hiding this comment.
| ==== Problem schema members, supported by the API guidelines | |
| ==== Problem object specification |
|
|
||
| The OpenAPI schema definition of the Problem JSON object can be found | ||
| ==== Problem schema members, supported by the API guidelines | ||
| Problem detail objects can have the following members described in the OpenAPI |
There was a problem hiding this comment.
| Problem detail objects can have the following members described in the OpenAPI | |
| The Problem object is specified in the OpenAPI |
| Clients may utilize properties in the Problem Object, particularly those | ||
| documented in the API specification. However, they *should not* depend on these | ||
| properties being present or having specific values. | ||
| The examples of such cases are: |
There was a problem hiding this comment.
| Clients may utilize properties in the Problem Object, particularly those | |
| documented in the API specification. However, they *should not* depend on these | |
| properties being present or having specific values. | |
| The examples of such cases are: | |
| Clients may use, but *should be robust and not* depend on the Problem | |
| properties being present or having specific values of specific types. | |
| The examples of such cases are: |
| 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.
| include `application/problem+json` in the {Accept}-Header to trigger delivery | ||
| of the extended failure information. | ||
|
|
||
| ==== Automated processing of Problem Object on client side |
There was a problem hiding this comment.
| ==== Automated processing of Problem Object on client side | |
| ==== Client processing of Problem Object |
There was a problem hiding this comment.
The client aspects mentioned in the sub-chapter above should be also mentioned here, shouldn't it?
| 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?
3 participants
Incorporate API Guild thoughts on detailing Problem Object guidelines (#763)