please at least include referer link in the response
JSON API
81–90 of 140 posts
Re: JSON API
#82I read a lot of RFCs and drafts for media types lately and what strikes me reading this spec is the very liberal use of MUST which seems to me like an unnecessary violation of the robustness principle, that Jon Postel introduced first in RFC761 (TCP). Mike Amundsen describes in his book 'Building Hypermedia APIs […]': Media type designers should keep Postel in mind. Designers can make supporting the Robustness Princi…
Postels law is the worst kind law ever made in IT. Take a look at how many security bugs that comes from being 'accepting' of bad HTML/CSS/Javacscrip/PDF files.
Be a nazi in what you accept, fail loudly and early enough and there will be no problem for the user to correct his error - it is only when you 50000 php pages full of echo statements that you can't change. If it had complained when he made the first, he wouldn't be in that situation now.
And don't tell me that nobody would use it then. C++, C# and Java are the top most used languages and they are all anal-retentive.
Re: JSON API
#83Earlier quoted context omitted.
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 about hypermedia instead of rels? ... 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 th…
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 ?.
Re: JSON API
#84It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…
It's JavaScript, that's the syntax notation for JavaScript objects. Sure it resembles lisp and python, but that's just how languages come to be. If I were to invent a new language, if likely use {} for dictionaries and [] for lists too.
Lisp is harder to read than JavaScript because it doesn't disambiguation between lists and dictionaries in a clear way like js and python do.
Re: JSON API
#85It amazes me how programming languages and APIs look more and more like Lisp. Modern languages copy essential features from Lisp, and JSON as one of the most popular JS libs almost look identical to Lisp s-expressions. Someday also more people will realize how useful and effective the equivalence of control structures and data really is. JSON: { "posts": { "id": "1", "title": "Rails is Omakase", "rels": { "author": 9…
Or in Clojure: { "posts" { "id" "1", "title" "Rails is Omakase", "rels" { "author" 9, "comments" [ 5, 12, 17, 20 ] } } } Commas are unnecessary, I kept them for clarity.
Wouldn't it be better to use keywords here?:
{ :posts { :id 1 :title "Rails is Omakase" :rels { :author 9 :comments [5 12 17 20] }}}Re: JSON API
#86Earlier quoted context omitted.
Or in Clojure: { "posts" { "id" "1", "title" "Rails is Omakase", "rels" { "author" 9, "comments" [ 5, 12, 17, 20 ] } } } Commas are unnecessary, I kept them for clarity.
I'm not sure I like this syntax. It's unfamiliar both to lispers and "mainstreamers". The former will be irritated with { and commas, the latter will try to insert : everywhere. I read an interview with Rich Hickey where he said that adding these three syntax constructs reduced cognitive burden on programmers. He meant () for lists, [] for vectors and {} for hashes. I should implement it in Racket and just see how it…
There was a discussion on the mailing list concerning colon in maps, here's the JIRA issue [1]. IIRC it was kind of decided to let it die, but maybe someone will implement it.
Personally I think that differentiating between lists and maps is important and the way Clojure does it (as well as JSON) is quite easy to write and read. FWIW example given by bitcracker is broken because there's no way to understand what does the following mean:
(rels (author 9) (comments (5 12 17 20)))
Re: JSON API
#87What timing! I just released the first version of a rails engine that automatically builds APIs to match Ember Data. It also uses active model serializers. Check it out here: https://github.com/southpolesteve/api_engine
I would love to get some feedback on the initial version. I will definitely be implementing more of the OP's spec this weekend.
Re: JSON API
#88First, I think it's awesome that you guys are documenting this for others to re-use, whether it ends up being the one true format or not. Having options to choose from is doubtlessly good.
Some thoughts:
1. I'm not sure about the name. There will definitely many JSON APIs that don't use (your) JSON API for a long time, even if this becomes hugely popular. I don't see how this will not lead to avoidable confusion in the future. Given that it's very document-centric, why not use something like "JSON Doc API" or similar?
2. In the ID approach, why are the base URIs the client needs to know about not always discoverable, e.g. using standard link relations? Or phrased differently, why would I ever not want to use the "URL Template Shorthands" approach mentioned later?
3. Why use application/json and not something more specific? I can see some reasons, but would be interested in yours.
4. On creation, if I accept the pain of generating an ID on the client and can construct the URI using the template, why can't I use PUT instead of POST?
5. If I use a POST to create something, why don't I get a 201 Created with a Location header?
6. I'd suggest to upgrade the "MAY" for caching to a "SHOULD".
/edited to match @steveklabnik's numbers
Re: JSON API
#89A few additions that I'd like to see:
* Standardized paging
* Optional side-loading - GET /albums.json?include=artists,songs
* Multiple meta elements - so we'd have "albums_meta", "artists_meta" and "songs_meta" in the example above. This allows us to include 'has_n' relationship paging data.
Re: JSON API
#90Earlier quoted context omitted.
> What's the reason for the top level rel? It seems like it's just there to stop the urls from being repeated and to save space, but isn't that what gzip is for? It also makes it possible to cache things locally indexed on their IDs, and to form URLs that make requests for just the precise documents that aren't available locally. In order to achieve this, it's necessary to have both (1) IDs, and (2) a way to convert…
> It also makes it possible to cache things locally indexed on their IDs, and to form URLs that make requests for just the precise documents that aren't available locally. In order to achieve this, it's necessary to have both (1) IDs, and (2) a way to convert a list of IDs into a single request for all of the documents at once. Couldn't the id column contain a canonical url then? E.g.: { "posts": { "id": "http://exam…
I think biggest benefit from this kind of specification would be for data (partly) distributed and (partly) shared between different hosts, as there would be at least some common ground for both clients and server how to communicate. IDs are very abstract and does not necessarily tie data under particular host. Of course for some data domains ID could be URL, but that is decision made by data provider. Spec decision would be crippling for overall use.