Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

JSON API

jsonapi.org

Post reply on HN
Print view View original

1–10 of 140 posts

Re: JSON API

#2

Post by rcsorensen »

It's great to see this laid out in a single place.

Couple of things that might be nice to see here:

* Pagination concerns

You call out "meta: meta-information about a resource, such as pagination", but that doesn't say whether things are 0/1 based, what the names of the values for per-page are, how to indicate length of the underlying collection, etc.

* Search concerns

I don't know whether this is an area that has best practices yet, but having it said and decided on something called "jsonapi.org" could save many people many hours of pain in the future.

* Elective compound documents

Bit more of a reach, but there have been a bunch of times I wanted to say "this resource, and these relations of it, and those relations of those". And in some cases partial documents (id and name alone) of those tertiary relations.

Re: JSON API

#3

Post by steveklabnik »

rcsorensen wrote: post #2

It's great to see this laid out in a single place. Couple of things that might be nice to see here: * Pagination concerns You call out "meta: meta-information about a resource, such as pagination", but that doesn't say whether things are 0/1 based, what the names of the values for per-page are, how to indicate length of the underlying collection, etc. * Search concerns I don't know whether this is an area that has be…

I am literally sitting on a plane right now, but as soon as I get off, will be registering this type with IANA. So that helps #2.

#3 will be do-able I think. I'm interested in this too.

#1 is something that needs a good answer, yes. I THINK it's out of the scope of this, as there are already registered REL values that handle this, but we should clarify.

I will be happy to answer anyone else's questions after I land, it's time to turn off electronic devices.

Re: JSON API

#5

Post by 1qaz2wsx3edc »

steveklabnik wrote: post #3
rcsorensen wrote: post #2

It's great to see this laid out in a single place. Couple of things that might be nice to see here: * Pagination concerns You call out "meta: meta-information about a resource, such as pagination", but that doesn't say whether things are 0/1 based, what the names of the values for per-page are, how to indicate length of the underlying collection, etc. * Search concerns I don't know whether this is an area that has be…

I am literally sitting on a plane right now, but as soon as I get off, will be registering this type with IANA. So that helps #2. #3 will be do-able I think. I'm interested in this too. #1 is something that needs a good answer, yes. I THINK it's out of the scope of this, as there are already registered REL values that handle this, but we should clarify. I will be happy to answer anyone else's questions after I land,…

Of all people.

What about hypermedia instead of rels?

I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's own collection?

For instances:

`GET /friends?ids=1,34,54`

Could be:

`GET /friends/best.json` and `best` to the system in some form, represents 1,34,54.

I don't want a RESTful JSON API. I want a REST JSON API.

Re: JSON API

#6

Post by calebio »

Is there any reason the top level objects are represented as an array of objects vs an object keyed on ID? Sure the ID would have to then be a string, but I feel that keying it on ID with direct lookup far outweighs having to search for your item each time.

I feel that if you have an author with many comments:

{ authors: { '1': { id: '1', comments: [1, 2] } }, comments: { '1': {}, '2': {} } }

it would be easier to say results['comments']['1'] instead of performing some type of search across them each time.

Re: JSON API

#7

Post by rcsorensen »

steveklabnik wrote: post #3
rcsorensen wrote: post #2

It's great to see this laid out in a single place. Couple of things that might be nice to see here: * Pagination concerns You call out "meta: meta-information about a resource, such as pagination", but that doesn't say whether things are 0/1 based, what the names of the values for per-page are, how to indicate length of the underlying collection, etc. * Search concerns I don't know whether this is an area that has be…

I am literally sitting on a plane right now, but as soon as I get off, will be registering this type with IANA. So that helps #2. #3 will be do-able I think. I'm interested in this too. #1 is something that needs a good answer, yes. I THINK it's out of the scope of this, as there are already registered REL values that handle this, but we should clarify. I will be happy to answer anyone else's questions after I land,…

I worded #2 really, really poorly.

I'd love to see a spec for how to search a collection against an API that is jsonapi compliant. Different folks are all over the place here.

The base URL for search is different for different API producers. I like

  GET /teams?homecity=los+angeles
but have also seen things like

  GET /search/teams?homecity=los+angeles
or

  GET /teams/search?homecity=los+angeles
How to specify mildly complex search parameters is also unclear in the world. For referenced objects "/teams?homecity.state=ca" seems to fit with the style used for URL templates.

For bounded queries, should it be mongodb style?

  GET /teams?homecity.population.$lt=100000&homecity.population.$gt=100
And since we're talking about searches and pagination, do we need to specify a parameter for ordering results?

  GET /teams?wins.$gt=3&$order=homecity.population.$desc

Re: JSON API

#8

Post by oinksoft »

calebio wrote: post #6

Is there any reason the top level objects are represented as an array of objects vs an object keyed on ID? Sure the ID would have to then be a string, but I feel that keying it on ID with direct lookup far outweighs having to search for your item each time. I feel that if you have an author with many comments: { authors: { '1': { id: '1', comments: [1, 2] } }, comments: { '1': {}, '2': {} } } it would be easier to sa…

Ordering. The ECMAScript standard does not specify property enumeration order.

Re: JSON API

#9

Post by pserwylo »

This is important. We've just been implementing a SOAP interface to our software, and have been discussing the best way to provide a JSON API using the same mechanism. The sticking point is probably that there is no standard way to define an API like there is with SOAP.

One question though: I notice that the language they use if very similar to a typical RFC. Is this an RFC? and if not, why? I'm a little naive about the process for submitting them and getting them accepted, but it would be great if this ended up as an official RFC that could be referred to just like SOAP/WSDL.

Post reply on HN