Skip to content

Example Error Objects #828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 26, 2015
Merged

Example Error Objects #828

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
56bdcb7
Example Error Objects
bf4 Aug 21, 2015
af0fe1f
Clean up error object examples
ethanresnick Aug 21, 2015
660d312
Merge pull request #1 from TechAtNYU/errors_example
bf4 Aug 23, 2015
523a24b
Incremental commit to aid in reviewing
bf4 Aug 23, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Incremental commit to aid in reviewing
  • Loading branch information
@bf4
bf4 committed Aug 23, 2015
commit 523a24b1c75bf8a19768e4c7f8a1be38ba0fc0e6
33 changes: 18 additions & 15 deletions examples/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,17 +227,17 @@ Content-Type: application/vnd.api+json
"errors": [
{
"status": "403",
"source": { "pointer": "data/attributes/secret-powers" },
"source": { "pointer": "/data/attributes/secret-powers" },
"detail": "Editing secret powers is not authorized on Sundays."
},
{
"status": "422",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having status in isolation seems a bit odd. In this example, I'd expect it to be part of the first error object.

I think an example that shows multiple different errors with different status values would be great. For example, one error object could be a 404 and another 422, and the status for the whole response could be 400.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thanks! I made it this way on purpose since I didn't understand when error objects might have different status attributes.

"source": { "pointer": "data/attributes/volume" },
"source": { "pointer": "/data/attributes/volume" },
"detail": "Volume does not, in fact, go to 11."
},
{
"status": "500",
"source": { "pointer": "data/attributes/reputation" },
"source": { "pointer": "/data/attributes/reputation" },
"title": "The backend responded with an error",
"detail": "Reputation service not responding after three requests."
}
Expand All @@ -247,7 +247,7 @@ Content-Type: application/vnd.api+json

The only uniqueness constraint on error objects is the `id` field. Thus,
multiple errors on the same attribute can each be given their own error
object. The example below shows multiple errors on the `first-name` attribute:
object. The example below shows multiple errors on the `"first-name"` attribute:

```http
HTTP/1.1 422 Unprocessable Entity
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

422 works here, but 400 is also valid, and some people still don't like using status codes from WebDAV for non-webDAV apps.

Therefore, maybe you could add a line at the bottom of this example saying that a 400 response would also be ok, and linking to that SO answer? I don't want JSON API to appear to be taking a position on 400 vs. 422 by only using one in our examples.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I admit I was unsure of which to choose in some of these examples.

Expand All @@ -256,12 +256,12 @@ Content-Type: application/vnd.api+json
{
"errors": [
{
"source": { "pointer": "data/attributes/first-name" },
"source": { "pointer": "/data/attributes/first-name" },
"title": "Invalid Attribute",
"detail": "First name must contain at least three characters."
},
{
"source": { "pointer": "data/attributes/first-name" },
"source": { "pointer": "/data/attributes/first-name" },
"title": "Invalid Attribute",
"detail": "First name must contain an emoji."
}
Expand Down Expand Up @@ -291,7 +291,7 @@ For the example below, imagine the API docs specifed the following mapping:
> | 226 | Passwords do not match |
> | 227 | Password cannot be one of last five passwords |

Multiple errors on `password` attribute, with error `code`:
Multiple errors on `"password"` attribute, with error `code`:

```http
HTTP/1.1 422 Unprocessable Entity
Expand All @@ -302,19 +302,19 @@ Content-Type: application/vnd.api+json
"errors": [
{
"code": "123",
"source": { "pointer": "data/attributes/first-name" },
"source": { "pointer": "/data/attributes/first-name" },
"title": "Value is too short",
"detail": "First name must contain at least three characters."
},
{
"code": "225",
"source": { "pointer": "data/attributes/password" },
"source": { "pointer": "/data/attributes/password" },
"title": "Passwords must contain a letter, number, and punctuation character.",
"detail": "The password provided is missing a punctuation character."
},
{
"code": "226",
"source": { "pointer": "data/attributes/password" },
"source": { "pointer": "/data/attributes/password" },
"title": "Password and password confirmation do not match."
}
]
Expand Down Expand Up @@ -351,19 +351,21 @@ Content-Type: application/vnd.api+json
{
"errors": [
{
"source": { "pointer": "/" },
"source": { "pointer": "" },
"detail": "Missing `data` Member at document's top level."
}
]
}
```

It uses `source` to point to the top-level of the document (`"/"`).
(Pointing to `"/data` would be invalid because the request document did
It uses `source` to point to the top-level of the document (`""`).
(Pointing to "/" would be an appropriate reference to the string
`"some value"` in the request document `{"": "some value"}`.
Pointing to `"/data"` would be invalid because the request document did
not have a value at `"/data"`, and `source` is always given with reference
to the request document.)

Note that if the server cannot parse the request as valid JSON, including
If the server cannot parse the request as valid JSON, including
`source` doesn't make sense (because there's no JSON document for `source` to
refer to). Here's how the server might respond to an invalid JSON document:

Expand Down Expand Up @@ -404,7 +406,8 @@ In most cases, JSON API requires the server to return an error when it encounter
an invalid value for a JSON API–defined query parameter. However, for API-specific
query parameters (i.e. those not defined by JSON API), a server may choose to
ignore an invalid parameter and have the request succeed, rather than respond with
an error. API-specific query paramters must contain one non a-z character.
an error. [API-specific query parameters must contain one non a-z
character.](http://jsonapi.org/format/#query-parameters)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this link to the merge commit

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


Other examples of invalid parameters include: `?felds[author]=` (invalid parameter name)
and `?redirect_to=http%3A%2F%2Fwww.owasp.org` (invalid parameter, in this case,
Expand Down
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy