Skip to content
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.

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

What to return if a collection is empty? #101

Closed
gabrielgrant opened this issue May 27, 2013 · 14 comments

Comments

@gabrielgrant
Copy link
Contributor

@gabrielgrant gabrielgrant commented May 27, 2013

What should be returned when an empty collection is queried?

a hash with an empty array?

example 1

GET /photos

HTTP/1.1 200 OK
Content-Type: application/json

{
  "photos": []
}

example 2

GET /photos

HTTP/1.1 200 OK
Content-Type: application/json

{
  "photos": [],
  "meta": {
    "client-ids": true
  }
}

or an empty hash?

example 3:

HTTP/1.1 200 OK
Content-Type: application/json

{}

example 4:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "meta": {
    "client-ids": true
  }
}

I think a hash with an empty array is probably less likely to cause surprises and would be happy to provide a patch if you agree.

@steveklabnik

This comment has been minimized.

Copy link
Contributor

@steveklabnik steveklabnik commented May 27, 2013

I'm about to get on a plane and don't have time to properly review the relevant part of the spec, but will come back to it later tonight.

My understanding at current would be that it's example 1, as per the spec right now. Why would it not be?

@gabrielgrant

This comment has been minimized.

Copy link
Contributor Author

@gabrielgrant gabrielgrant commented May 27, 2013

sorry, just updated the issue to number my examples sanely -- i assume you were referring to the first example 1 (not the second one that is now example 3)?

like i said, my assumption is that example 1 & 2 are correct, but thought it should be spelled out explicitly. Right now the spec covers the cases of "singular resources" and says when "the length of an array at a resource key is greater than one, the value represents a list of documents." But it doesn't specify anything for the case when a resource collection is empty.

sorry if I'm being too pedantic... but that's kind of what specs are all about, right? :)

@steveklabnik

This comment has been minimized.

Copy link
Contributor

@steveklabnik steveklabnik commented May 27, 2013

Specs are about being pedantic, but there's also a level of explicitness vs. implicitness.

I don't think that this should belong in the spec proper, but I wouldn't mind it being in the examples. (and i meant 1)

@gabrielgrant

This comment has been minimized.

Copy link
Contributor Author

@gabrielgrant gabrielgrant commented May 27, 2013

also: have a good flight!

@gabrielgrant

This comment has been minimized.

Copy link
Contributor Author

@gabrielgrant gabrielgrant commented May 27, 2013

woops, deleted my actual comment :P

Yes, I agree: at a certain point, overly-explicit documents just become basically unreadable. RFC 6902 has an appendix of specific examples to keep the core spec more lean. Are you alright with me adding one of those to JSON API?

@steveklabnik

This comment has been minimized.

Copy link
Contributor

@steveklabnik steveklabnik commented May 27, 2013

Yes, I wanted to do it myself, but if you're willing, please do.

On Mon, May 27, 2013 at 11:38 AM, Gabriel Grant notifications@github.com
wrote:

woops, deleted my actual comment :P

Yes, I agree: at a certain point, overly-explicit documents just become basically unreadable. The RFC 6902 has an appendix of specific examples to keep the core spec more lean. Are you alright with me adding one of those to JSON API?

Reply to this email directly or view it on GitHub:
#101 (comment)

@ahx

This comment has been minimized.

Copy link
Contributor

@ahx ahx commented Jun 3, 2013

When using the full-url style in the links object, what would you return for an empty relation?
I think to just omit the attribute might be problematic, so we should return null instead, right?

Example 1: A Post with an Author and Comments:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "http://example.com/people/1",
      "comments": "http://example.com/comments/5,12,17,20"
    }
  }]
}

Example 2: A Post without an Author or Comments:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": null,
      "comments": null
    }
  }]
}
ethanresnick added a commit to ethanresnick/json-api that referenced this issue Jul 28, 2014
@steveklabnik steveklabnik reopened this Sep 17, 2014
@steveklabnik

This comment has been minimized.

Copy link
Contributor

@steveklabnik steveklabnik commented Sep 17, 2014

Especially now that we have single responses with no arrays, we should explicitly mention this in the spec.

@dgeb

This comment has been minimized.

Copy link
Member

@dgeb dgeb commented Sep 17, 2014

Here's my take on these various issues:

A request for a collection can still return an empty array:

GET /photos

HTTP/1.1 200 OK
Content-Type: application/json

{
  "photos": []
}

A request that for a single resource can return a 404 (with or without an error object):

GET /photos/1

HTTP/1.1 404 Not found

A request for multiple individual resources can also return a 404 along with error objects that enumerate the missing resources.

Has-one relationships that are blank should be null, as in @ahx's example 2 above:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": null,
      "comments": null
    }
  }]
}

@steveklabnik do you agree with all the above? If so, I agree that some of these points could be better spelled out in the spec, especially the point about null values.

@steveklabnik

This comment has been minimized.

Copy link
Contributor

@steveklabnik steveklabnik commented Sep 17, 2014

I agree that all these are reasonable, yes.

@diosney

This comment has been minimized.

Copy link
Contributor

@diosney diosney commented Sep 17, 2014

Just as a sidenote, I've been using for a while @dgeb approaches for cases 1 (200 with empty array on collections) and 2 (404 on single resources) and so far is working for me very smoothly.

@dgeb

This comment has been minimized.

Copy link
Member

@dgeb dgeb commented Sep 17, 2014

@steveklabnik I'll send a PR to clarify null relationships

@diosney nice! 👍

@dgeb

This comment has been minimized.

Copy link
Member

@dgeb dgeb commented Sep 17, 2014

I missed something when I copied that example from @ahx. I did mean that has-many relationships should be represented by an empty array and only has-one relationships should be represented by null.

This is corrected:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": null,
      "comments": []
    }
  }]
}
dgeb added a commit to dgeb/json-api that referenced this issue Sep 17, 2014
Has-one relationships: `null`
Has-many relationships: `[ ]`

[Closes json-api#101]
@dgeb

This comment has been minimized.

Copy link
Member

@dgeb dgeb commented Feb 19, 2015

I believe this is all clarified in the spec as of #341 (RC2)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.