Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updates message/error-reporting.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-02-14 10:43:42 +00:00
parent fdd5652ce3
commit 7f405ca8e1
1 changed files with 40 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
message/error-reporting.md
View File

@@ -1,7 +1,36 @@
# Error Reporting
The [`application/vnd.error+json`](https://github.com/blongden/vnd.error) (vnd.error) MUST be used to communicate details about an error.
The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) (Problem Detail) **MUST** be used to communicate details about an error.
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 minimum, any Problem Detail response **MUST** have the `title` and `detail` fields.
#### Example
```json
{
"title": "Authentication required",
"detail": "Missing authentication credentials for the Greeting resource."
}
```
## Optional Fields
It **SHOULD** have the `type` field with the identifier of the error, in addition it **MAY** have the `instance` field with the URI of the resource in question. If the Problem Details responses has the `status` field it **MUST** have the same value as HTTP Status code from of the response.
```json
{
"type": "https://adidas-group.com/problems/scv/unauthorized",
"title": "Authentication required",
"detail": "Missing authentication credentials for the Greeting resource.",
"instance": "/greeting",
"status": 401
}
```
## Additional Fields
If needed, the Problem Detail **MAY** include additional fields, refer to [RFC7807](https://tools.ietf.org/html/rfc7807) for details.
> vnd.error media type is intended for use with the HTTP status codes 4xx and 5xx, though this does not exclude it from use in any other scenario.
#### Example
A request is made to retrieve a resource representation:
@@ -11,23 +40,22 @@ GET /greeting HTTP/1.1
Accept: application/hal+json
```
However in order to make this request the client needs to be authorized. Since the request is made without the authorization credentials the **401 Unauthorized** response is returned together with details using the `vnd.error+json` media type:
However in order to make this request the client needs to be authorized. Since the request is made without the authorization credentials the **401 Unauthorized** response is returned together with details using the `application/problem+json` media type:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.error+json
Content-Type: application/problem+json
Content-Language: en
{
"message": "Authentication required. Missing authentication credentials for the target resource.",
"logref": "REQ0001,
"_links": {
"about": {
"href": "/greeting"
}
}
"type": "https://adidas-group.com/problems/scv/unauthorized",
"title": "Authentication required",
"detail": "Missing authentication credentials for the Greeting resource.",
"instance": "/greeting",
"status": 401
}
```
The `about` link relation type is the resource (URI) this vnd.error instance is about.