From 3afbf431037547556c09f53e387235baa5db2170 Mon Sep 17 00:00:00 2001 From: Andrzej Date: Tue, 26 Feb 2019 10:53:04 +0100 Subject: [PATCH] Add clarification on problem detail fields --- .../functionality/message/error-reporting.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/functionality/message/error-reporting.md index d6e22a7..8ec785a 100644 --- a/rest-api-guidelines/functionality/message/error-reporting.md +++ b/rest-api-guidelines/functionality/message/error-reporting.md @@ -4,7 +4,7 @@ The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) \(Problem Problem Detail is intended for use with the HTTP status codes 4xx and 5xx. Problem Detail **MUST NOT** be used with 2xx status code responses. -At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. +At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1) ### Example @@ -15,6 +15,8 @@ At the minimum, any Problem Detail response **MUST** have the `title` and `detai } ``` +> NOTE: `title` and `detail` fields **SHOULD NOT** be parsed to determine the nature of the error. Instead `type` **MUST** be used. + ## Optional Fields It **SHOULD** has the `type` field with the identifier of the error, besides it **MAY** have the `instance` field with the URI of the resource in question. If the Problem Detail response has the `status` field it **MUST** have the same value as HTTP Status code from of the response. @@ -39,7 +41,7 @@ If needed, the Problem Detail **MAY** include additional fields, refer to [RFC78 When necessary, a Problem Detail response **MAY** include additional error details about the problems that have occurred. -These additional errors **MUST** be under the `errors` and **MUST** follow the Problem Detail structure. +These additional errors **MUST** be under the `errors` collection and **MUST** follow the Problem Detail structure. ### Example @@ -126,5 +128,4 @@ An API description **SHOULD** list all the error codes with which the API respon ## External resources -There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). - +There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). \ No newline at end of file