please at least include referer link in the response
That'd normally be included in headers, it's not really relevant to a media type.
JSON API
101–110 of 140 posts
Re: JSON API
#102Earlier 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.
Wouldn't it be better to use keywords here?: { :posts { :id 1 :title "Rails is Omakase" :rels { :author 9 :comments [5 12 17 20] }}}
Yes, this is the usual way in Common Lisp.
Re: JSON API
#103A 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.
Thanks for the feedback :) Standardized paging seems to come up a lot, so it seems like a good thing to add once the core spec stabilizes. Optional sideloading also has come up a few times, and seems easy to add as a MAY in the spec. I need to flesh out the meta stuff in general, and the ability to have "meta anywhere" as well as top-level metas is coming.
Nice, thanks. I've been building an alternative to ActiveModel::Serializers which provides these features.
https://github.com/RestPack/restpack-serializer
In the light of your proposals, I'll either implement JSON API or switch back to AM:Serializers. Side-loading, paging and Ember Data compatibility are my main goals.
Re: JSON API
#104Earlier quoted context omitted.
You've just summed up what bothers me about this format.
This sounds to me as if you're not really in search of a loosely coupled hypermedia API schema, but an RPC mechanism.
Exactly the oposite, I don't want a scheme that's tied to assumptions based on relational databases.
Re: JSON API
#105Earlier quoted context omitted.
The thing is that "JSON API" was not available, it's already in common use to describe APIs that use JSON. "HAL" is totally not the same, it's clearly a name chosen to not conflict with existing terminology. The proper layer for caching is HTTP, do we really want to end up with duplicated overlapping functionality between the layers? I see you have an application specific need for a certain thing but I don't think it…
> The proper layer for caching is HTTP, do we really want to end up with duplicated overlapping functionality between the layers? HTTP caching doesn't work well with compound documents that represent a graph of objects. The kind of caching described in JSON API allows an application to group together requests for documents while avoiding making requests for documents it already has. The only way HTTP caching works is…
> This functionality was extracted out of a general purpose framework used by a number of applications that made heavy use of it
That's exactly it! This looks like a sensible design for an API served from rails and consumed by Ember.JS. It's just over selling it a bit to imply that this should be how all JSON APIs should be.
Re: JSON API
#106Earlier quoted context omitted.
> 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…
How would you combine multiple authors into a single request? With IDs + a template, you can form a single request for all of the "people" you don't have yet. If you use URLs as IDs, which is one of the primary goals here.
If I understand your question correctly, I would say that http pipelining solves that issue. It can only be used for GET requests, so there are limitations.
Re: JSON API
#107Earlier quoted context omitted.
> 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…
I'd say it's the other way around. Url's are opaque for the client - id's imply more knowledge of the implementation. E.g. the client would have to know which host to communicate with and how to structure url's from id's. With hyperlinked documents, all the client needs to know is http.
Re: JSON API
#108Earlier quoted context omitted.
> The proper layer for caching is HTTP, do we really want to end up with duplicated overlapping functionality between the layers? HTTP caching doesn't work well with compound documents that represent a graph of objects. The kind of caching described in JSON API allows an application to group together requests for documents while avoiding making requests for documents it already has. The only way HTTP caching works is…
> This functionality was extracted out of a general purpose framework used by a number of applications that made heavy use of it That's exactly it! This looks like a sensible design for an API served from rails and consumed by Ember.JS. It's just over selling it a bit to imply that this should be how all JSON APIs should be.
I don't think "served from Rails" and "consumed by Ember.js" is quite right. It was designed to work with existing servers that have facilities for easily generating JSON (Rails, Django, various Node frameworks), and smart clients that want to index local data by ID (Angular, Backbone, Ember, etc).
In short, it's an attempt to extract the learnings about efficiently transporting a non-trivial number of objects over a REST-like transport in a sometimes-incremental way. Many different server/client combinations have been attempting to do this in an ad-hoc way for years, and Ember Data was simply an attempt to try something general-purpose out in the real world.
Re: JSON API
#109First, 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 t…
> I'm not sure about the name Good feedback. Many people have said this, and I'm thinking about an alternative. > Or phrased differently, why would I ever not want to use the "URL Template Shorthands" approach mentioned later? You can think of the ID-based approach as just coming with a set of default URL templates in a top-level rel. The primary reason I included it (and I considered not including it), is that it ma…
> You can think of the ID-based approach as just coming with a set of default URL templates in a top-level rel.
Then I'd be perfectly happy. But why is the paragraph that mentions exactly this ("... The top-level of a JSON API document MAY have the following keys") in the "URL-Based JSON API" section?
> You think a server SHOULD use HTTP caching?
No, you're probably right - a SHOULD is too strong. I guess my reaction was more negative to the "MAY" in your text about caching than anything else. The caching section (which is currently in the writing document?) doesn't seem to actually add much value beyond what HTTP says anyway. Maybe dropping it is the easiest path?
Re: JSON API
#110Earlier quoted context omitted.
How would you combine multiple authors into a single request? With IDs + a template, you can form a single request for all of the "people" you don't have yet. If you use URLs as IDs, which is one of the primary goals here.
If I understand your question correctly, I would say that http pipelining solves that issue. It can only be used for GET requests, so there are limitations.
It can only be used for GET requests, has problems in web browsers, and still requires the overhead of individual requests on the server side to construct and return many responses.
In theory, things like pipelining allow you to never have to worry about compound documents. In practice, I don't know anyone who has gotten this to work well for browser clients and general-purpose frameworks when dealing with non-trivial numbers of documents.