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.
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
but have also seen things like or 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?
And since we're talking about searches and pagination, do we need to specify a parameter for ordering results?