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.
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.
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
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).
It's close in a lot of ways, I didn't want to mention a specific format and get bogged down on it's discussion but more over what I think a JSON API standard should be.
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.
I'm sorry, I'm very confused here. Why does hypermedia let you get rid of link relations?
How is a 'resource template' different than a <form> hypermedia control in HTML?
Why does the URI format matter? It's hypermedia, that's basically irrelevant.
It seems you want a "REST"ful API, and that's great. Build that. But then why the first sentence being seemingly upset with some sort of lack of imagined hypermedia support?
... can you elaborate a bit more on what this means? I don't understand what you're trying to say.
> I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's own collection?
I'm not 100% sure what you mean here either, but I'm reading it as "Why not use a comma rather than passing a list of GET parameters?"
The answer is "I don't think that's particularly important either." Constructing your own URIs is against the very spirit of REST. Let the server do that for you.
I think 1qaz2wsx3edc means naming the key "hypermedia" instead of "rels". I don't like "rels" because it's hard to pronounce (do I say relationships or rails?) and because it it's an abbreviation. Unfortunately I can't think of something better.
When you're competing against nothing, lack of elegance is a difficult problem. The need to be elegant is stronger and you can't simply be as or more elegant than your competition.
You shouldn't ever request ids from a server, you should request id -- as a single item -- or a collection defined by the server and named (such as user/friends.json, not users?id=for,bar,baz,foobar).
Basically rest apis map exactly one resource to a url and should never use the hack that is ?.
That is simply not true. Can you provide me with some sort of citation on this? Fielding doesn't talk about URL construction in his thesis, and, in fact, specifically mentions things like collections and multiple entities residing in one resource.
Also, ? is not a 'hack', I don't know where you're getting that from either.
I used URL Templates (RFC 6570 - http://tools.ietf.org/html/rfc6570) so that the request to the server is not ad-hoc, but instead fully described by the resource body.
Indeed. And importantly, this API makes it possible to restrict the query to a list of documents that the client doesn't already have from another source. In practice, once you start using compound documents with an identity map, there are many cases where existing documents exist on the client and shouldn't be re-fetched.
One really simple example is having a number documents that are related to "people" documents. For example, imagine a blog with blog posts and comments, each of which point at an author. When a list of comments for a post is downloaded, each comment will point to an author. Some of those authors will be the same, and some of them will already have been seen from previous posts. This structure allows the client to request only the authors that have not yet been seen (and if you're lucky, it may even be the empty set!).
Think of it like you're trash bin, you move the files there, one at a time, then empty. State is captured. Then invoked. This is only necessary for transactional requirements.
Another method is having a collection sorted and slices.
DELETE /teams?id[gt]=10&id[lt]=13
As for non-sequel ids or random ids. It could be possible to support ?id[]=12&id[]=9&id[]=4. Sure it could be /teams/1,2,3 this is just a small detail of the parser. I'm more interesting in how a collection is queried and represented.
Actually, the current Ember Data protocol uses ?id[]=12&id[]=9&id[]=4. There's no good reason for the extra verbosity; it's pretty easy to split over commas and the current format is tricky to parse for platforms that don't already understand it.
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.