Example Error Objects #828

bf4 · 2015-08-05T19:24:25Z

Per discussion with @dgeb in rails-api/active_model_serializers#1004

Although it is still compliant to represent multiple validation errors in the same error object,
it's not ideal. I would recommend creating a unique error object per validation error,
so that fields such as code and title can be used consistently and expressively across errors.
For instance, one code might indicate that a field is too short, and another might indicate
that invalid characters were used. If you try to combine these errors into a single code,
then it will probably end up being something more generic with less meaning, such as "invalid value".

References:

dgeb · 2015-08-05T20:06:16Z

examples/index.md

+{
+  "errors": [
+    {
+      "source": { "pointer": "data/attributes/first_name" },


Although underscores are compliant, I'd prefer to use dasherized names, such as first-name, in examples as per our recommendations.

steveklabnik · 2015-08-05T20:09:30Z

Thanks for this! Good examples are so crucial to getting a spec adopted.

dgeb · 2015-08-05T20:10:15Z

examples/index.md

+      "detail": "is too short"
+    },
+    {
+      "status": "422",


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.

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

dgeb · 2015-08-05T20:20:18Z

Thanks for this! Good examples are so crucial to getting a spec adopted.

Agreed! Great start here, @bf4 👍

bf4 · 2015-08-06T02:44:24Z

I've made some updates, there might be some code blindness going on here.. I'm not sure if I did 'parameter' right. It appears to have evolved from 'path'.

I'm also thinking about adding examples of an error object with

a links object
a meta object
a source pointer to a 'primary' data object.

And a response with, in addition to an errors top-level member, the other valid top-level members

meta: a meta object that contains non-standard meta-information.
jsonapi: an object describing the server's implementation
links: a links object related to the primary data. (?)

bf4 · 2015-08-11T17:35:46Z

@dgeb @steveklabnik Any more feedback on the changes? (I've made them in incremental commits)

dgeb · 2015-08-11T18:44:31Z

examples/index.md

+{
+  "errors": [
+    {
+      "id": "ds.errors.invalid-error-expects-json-api-format",


This looks more like a code than an id:

id: a unique identifier for this particular occurrence of the problem.
code: an application-specific error code, expressed as a string value.

Oh, looks like I somehow mixed up code and id here and in the error codes section as well

FWIW, I got it from https://github.com/emberjs/data/blob/d842890357840700f0ee17f152415be0cba16030/packages/ember-data/lib/adapters/errors.js#L82

Ember.deprecate('`InvalidError` expects json-api formatted errors.', false, { id: 'ds.errors.invalid-error-expects-json-api-format', until: '2.0.0' });

which I misread as an errors object

dgeb · 2015-08-11T19:55:04Z

examples/index.md

+```
+
+```http
+HTTP/1.1 404 Not Found


Should be 400, since errors include 404 and 403 statuses.

bf4 · 2015-08-12T01:39:04Z

examples/index.md

+      "source": { "pointer": "data/relationships/author" },
+      "detail": "Post author cannot be blank."
+    }
+  ]


refs in the wild:

https://github.com/cerebris/jsonapi-resources/blob/28ac3971f8b9e73073575d41439ffe263d7e56f5/test/controllers/controller_test.rb#L452-L462

bf4 · 2015-08-12T02:05:49Z

@dgeb updated and rebased and added a few more source examples. What would a meta example be in an error object (not top-level member meta)?

bf4 · 2015-08-17T01:04:20Z

New and improved ✨

ethanresnick · 2015-08-17T07:49:41Z

examples/index.md

+    {
+      "title": "Adapter Error",
+      "code": "ds.errors.invalid-error-expects-json-api-format",
+      "detail": "The adapter rejected the commit because it was invalid"


Can you make the detail message here a bit more distinct than the title than it is now?

Also, can you add status to one of the earlier examples, in addition to having it on the one below? I don't want to imply through the examples that status is only applicable in cases where there are multiple errors returned at once. It can be useful too when the code processing the JSON isn't directly aware of the HTTP response (and could be useful also if JSON API is eventually used over non-HTTP protocols).

Sure. FWIW, I got that example title/code/detail off of the ember-data project :).

ethanresnick · 2015-08-23T02:23:15Z

examples/index.md

+    },
+    {
+      "code":   "225",
+      "source": { "pointer": "data/attributes/password" },


ethanresnick · 2015-08-23T02:26:50Z

@bf4 Thanks for all your hard work! This looks great to me now.

Please fix the small errors with the JSON Pointers, and then I think this is good to merge, unless @dgeb or @tkellen want to review it first.

bf4 · 2015-08-23T02:31:29Z

Merge commit amended and force-pushed.

ethanresnick · 2015-08-23T02:39:21Z

examples/index.md

+}
+```
+
+It uses `source` to point to the top-level of the document (`"/"`).


This line needs to say "" instead of the old "/".

Also, I think my comment about why "/" is inappropriate got accidentally merged into the response. It doesn't make sense there, though, because my example document with {"": "some value"} is missing, and because a server isn't allowed to respond with comments in its JSON. If you want to explain why "" is used rather than "/", please do it in this paragraph instead.

you a copy editor or I'm just tired of re-reading this ? :)

Maybe both :)

Added an incremental commit to address this to aid in future reviewing. I'll rebase into the merge commit once we're happy.

ethanresnick · 2015-08-23T02:39:39Z

👍

bf4 · 2015-08-23T02:58:03Z

fixing merge conflict... hold on

Clean up error object examples

bf4 · 2015-08-23T03:27:01Z

rebased

bf4 · 2015-08-26T14:28:45Z

@ethanresnick LGTM?

ethanresnick · 2015-08-26T16:06:26Z

LGTM. Merged.

Example Error Objects

Another small complement to json-api#863, to accommodate the table in json-api#828

bf4 · 2015-08-26T19:31:19Z

omg omg 🎆 🌈 ❗ 💥 👯 ❤️ 😍 😃 💯

joaomdmoura · 2015-08-26T19:33:27Z

🎉 🎉 🎉 🎉 🎉

dgeb · 2015-08-26T19:36:31Z

Really pleased to see this merged. We've needed some error examples for months.

@bf4 thanks for all your work here! 💯

@ethanresnick thanks for finishing the review! 🎉

Another small complement to json-api#863, to accommodate the table in json-api#828

bf4 force-pushed the errors_example branch 3 times, most recently from c83632b to d985b6d Compare August 5, 2015 19:29

bf4 mentioned this pull request Aug 5, 2015

[RFC] JSON API Errors (Initial implementation and roadmap for full feature-set) rails-api/active_model_serializers#1004

Merged

28 tasks

dgeb reviewed Aug 5, 2015
View reviewed changes

bf4 mentioned this pull request Aug 7, 2015

Pagination Links rails-api/active_model_serializers#1041

Merged

dgeb reviewed Aug 11, 2015
View reviewed changes

bf4 force-pushed the errors_example branch from b6bf748 to f75f65d Compare August 11, 2015 19:33

dgeb reviewed Aug 11, 2015
View reviewed changes

examples/index.md

```

```http

HTTP/1.1 404 Not Found

Copy link

Member

dgeb Aug 11, 2015

Choose a reason for hiding this comment

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

Should be 400, since errors include 404 and 403 statuses.

bf4 force-pushed the errors_example branch from 18b3b85 to c8cc530 Compare August 12, 2015 01:37

bf4 reviewed Aug 12, 2015
View reviewed changes

ethanresnick reviewed Aug 17, 2015
View reviewed changes

ethanresnick reviewed Aug 23, 2015
View reviewed changes

examples/index.md

},

{

"code": "225",

"source": { "pointer": "data/attributes/password" },

Copy link

Member

ethanresnick Aug 23, 2015

Choose a reason for hiding this comment

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

Ditto

bf4 force-pushed the errors_example branch from 2cc93bd to a489d72 Compare August 23, 2015 02:30

ethanresnick reviewed Aug 23, 2015
View reviewed changes

bf4 force-pushed the errors_example branch from e96eb4e to 5eba328 Compare August 23, 2015 03:17

bf4 and others added 3 commits August 22, 2015 23:23

Example Error Objects

56bdcb7

Clean up error object examples

af0fe1f

Merge pull request #1 from TechAtNYU/errors_example

660d312

Clean up error object examples

bf4 force-pushed the errors_example branch from 5eba328 to 523a24b Compare August 23, 2015 03:26

Incremental commit to aid in reviewing

523a24b

ethanresnick added a commit that referenced this pull request Aug 26, 2015

Merge pull request #828 from bf4/errors_example

13e0f00

Example Error Objects

ethanresnick merged commit 13e0f00 into json-api:gh-pages Aug 26, 2015

ethanresnick added a commit to ethanresnick/json-api-1 that referenced this pull request Aug 26, 2015

Improve table styling

d7ae1ac

Another small complement to json-api#863, to accommodate the table in json-api#828

ethanresnick mentioned this pull request Aug 26, 2015

Improve table styling #864

Merged

bf4 deleted the errors_example branch August 26, 2015 19:31

benoittgt pushed a commit to benoittgt/json-api that referenced this pull request Aug 27, 2015

Improve table styling

55269fe

Another small complement to json-api#863, to accommodate the table in json-api#828

benoittgt mentioned this pull request Aug 28, 2015

Add recommendations for asynchronous processing #792

Merged

bf4 mentioned this pull request Sep 22, 2015

Add 'things I link to' bf4/bf4.github.com#7

Open

NullVoxPopuli mentioned this pull request Mar 7, 2016

Serializing errors rails-api/active_model_serializers#933

Closed

Example Error Objects #828

Example Error Objects #828

Uh oh!

Conversation

bf4 commented Aug 5, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steveklabnik commented Aug 5, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dgeb commented Aug 5, 2015

Uh oh!

bf4 commented Aug 6, 2015

Uh oh!

bf4 commented Aug 11, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bf4 commented Aug 12, 2015

Uh oh!

bf4 commented Aug 17, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethanresnick commented Aug 23, 2015

Uh oh!

bf4 commented Aug 23, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethanresnick commented Aug 23, 2015

Uh oh!

bf4 commented Aug 23, 2015

Uh oh!

bf4 commented Aug 23, 2015

Uh oh!

bf4 commented Aug 26, 2015

Uh oh!

ethanresnick commented Aug 26, 2015

Uh oh!

bf4 commented Aug 26, 2015

Uh oh!

joaomdmoura commented Aug 26, 2015

Uh oh!

dgeb commented Aug 26, 2015

Uh oh!

Uh oh!

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