This is great, but I can't seem to be able to find the NoSQL flavored support. Seems great for relational style data models, but (I'm sure I'm missing something) I didn't see support for full nested document models. Did I entirely miss the point?
JSON API
11–20 of 140 posts
Re: JSON API
#12Is 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.
The related documents are indexed by id from the primary document, so ordering doesn't matter, and it makes sense to use a format suggested by calebio, as it's both more efficient and terse. However, the primary document and other nested entities which require ordering should return an array of objects.
Edit: clarification
Re: JSON API
#13Earlier quoted context omitted.
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.
Things bothering me in this proposal: the need for the relation; the use of "posts/1,2,3" to represent a list of resources; the "resource template". None of these are needed with REST/Hypermedia.
I've been using djangorestframework, and one of the things that I love about it (instead of tastypie) is the "Browsable API" renderer/parser mode. It's an excellent way to see if your API makes sense: if I'm not able to discover/manipulate resources just by clicking on the links or posting forms, it is a sign that the API design is ill-conceived.
Re: JSON API
#14This 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…
RFC vocabulary, and indeed, the entire format is perfect for writing specifications. And software people have become good at reading them. So it's common to see it outside IETF standards and docs.
Re: JSON API
#15Earlier quoted context omitted.
Ordering. The ECMAScript standard does not specify property enumeration order.
The related documents are indexed by id from the primary document, so ordering doesn't matter, and it makes sense to use a format suggested by calebio, as it's both more efficient and terse. However, the primary document and other nested entities which require ordering should return an array of objects. Edit: clarification
I may be missing something, but how is searching an array of JSON objects more efficient than direct lookup by ID?
Re: JSON API
#16Earlier quoted context omitted.
The related documents are indexed by id from the primary document, so ordering doesn't matter, and it makes sense to use a format suggested by calebio, as it's both more efficient and terse. However, the primary document and other nested entities which require ordering should return an array of objects. Edit: clarification
I may be missing something, but how is searching an array of JSON objects more efficient than direct lookup by ID?
I agree with you. "OP" was referring to your suggestion. I edited my pervious comment to clarify.
Re: JSON API
#17Earlier quoted context omitted.
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.
What if I've selected 5 arbitrary people to unfriend?
`PUT /friends/???.json`
Re: JSON API
#18Earlier quoted context omitted.
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 compl…
GET /teams/search?homecity=los+angeles
Wouldn't this be:
GET /teams/los+angeles
We could have query-able attributes, this is where I think OPTION verb should come into play. So I would OPTION /teams. This returns some JSON with the meta information about the collection, for instance: `{key :'wins', type: 'string', description: 'some api description', sortable => true, filter: true, group_by: false }`, this should probably hint at the abilities of the attribute (sortable/filter/group_by). This really raises the question of what is a good querying api for collections? I think our answer may be in the form SQL-like interface.
GET /teams?wins[gt]=1&losses[gt]=1&wins[sort]=desc&limit=10&offset=0
SELECT * FROM teams WHERE wins > 1 AND losses gt > 1 ORDER BY wins LIMIT 10 OFFSET 0
So what about support ORs or Unions and Joins? Well, ORs are simple they could act like a named scope.
GET /teams?wins_or_losses[gt]=1&wins[sort]=desc&limit=10&offset=0
SELECT * FROM teams WHERE (wins > 1 OR losses gt > 1) ORDER BY wins LIMIT 10 OFFSET 0
What about a Union or Join? These should be handled by a new endpoint (joins) or avoided by querying individual collections (unions).
Re: JSON API
#19This 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…
I find the MUST/SHOULD/MAY (NOT) wording so natural and obvious that I end up using it pretty much anywhere it's applicable, and I assume I'm not alone in that. I do sometimes edit out the caps, though.
Re: JSON API
#20Earlier quoted context omitted.
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 compl…
GET /teams/search?homecity=los+angeles Wouldn't this be: GET /teams/los+angeles We could have query-able attributes, this is where I think OPTION verb should come into play. So I would OPTION /teams. This returns some JSON with the meta information about the collection, for instance: `{key :'wins', type: 'string', description: 'some api description', sortable => true, filter: true, group_by: false }`, this should pro…
Isn't this what OData is trying to establish?
Quick intro video http://www.odata.org
Query formatting documentation http://www.odata.org/documentation/odata-v2-documentation/ur...
JSON representation documentation http://www.odata.org/documentation/odata-v2-documentation/js...