Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

JSON API

jsonapi.org

Post reply on HN
Print view View original

111–120 of 140 posts

Re: JSON API

#111

Post by wycats »

troels wrote: post #107
Orva wrote: post #90

Earlier quoted context omitted.

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.

URLs are opaque, and can often serve as very useful IDs, but, alone, they imply a one-at-a-time model of fetching documents, and this spec is trying to provide a way to easily request only the documents a client needs in a compound document.

Keep in mind that this spec actually requires that every ID be able to be readily converted into a URL based on information found in the same payload, so URLs are still front-and-center in the design. It just separates out the notion of a unique identifier, so that it can be used in other kinds of requests.

Re: JSON API

#112

Post by wycats »

tomjen3 wrote: post #83
steveklabnik wrote: post #52

Earlier quoted context omitted.

> 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 ?.

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.

Re: JSON API

#113

Post by orijing »

bitcracker wrote: post #60

It 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…

Relevant:

http://paulgraham.com/icad.html

Re: JSON API

#114

Post by stilkov »

steveklabnik wrote: post #95
stilkov wrote: post #88

First, 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…

1. All media types are 'document centric.' And real REST APIs serve up documents. So seems fine to me. Also, IANA does not have a 'api+json' type registered (until I did so last night), so the name isn't taken. 2. If you're transitioning _to_ this kind from some sort of older kind. Remember, this is extracted from real, working software; it's not some sort of thing we imagined up. Not everyone is super on the hyperme…

> 1. All media types are 'document centric.'

What I meant is that this is a particular kind of backend API, a very "model-centric" one. Nothing wrong with that, I just don't think this is the one and only kind and thus should take on the generic name.

> 2. If you're transitioning _to_ this kind from some sort of older kind.

Understood. Maybe an approach is to allow for this to specified optionally, with the fallback of being hard-coded if it's not present?

Re: JSON API

#115

Post by troels »

wycats wrote: post #110
troels wrote: post #106

Earlier quoted context omitted.

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-trivi…

I see.

The server side support seems like the wrong thing to base the protocol design on, but I admit that is probably just me showing my limited experience with very high traffic api's. I would think though that much of this could be alleviated by proper caching. As requests would naturally be finely granulated into individual resources, presumably that could be done efficiently.

The point of browser support is probably more pressing. I'm curious as to how big an issue that still is? Which browsers support it properly these days and which don't?

I wonder if it would be worth to build an api around the assumption of support for pipelining and then provide a fallback hack for those that lack support. E.g. something similar to the good old _method hidden-field hack for lack of http method support. I'm thinking something like an optional "batch request endpoint", that would tunnel through multiple requests, similar to what a pipeline would do. I believe Facebook is offering something similar in their api's.

Re: JSON API

#116

Post by [deleted] »

wycats wrote: post #108
almost wrote: post #105

Earlier quoted context omitted.

> 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…

[deleted]

Re: JSON API

#117

Post by vsync »

arianvanp wrote: post #70
bitcracker wrote: post #66

Earlier quoted context omitted.

> "could I express this as s-expressions?" Sure. "Would I want to?" Hell no. Of course it is possible to implement syntactic sugar in Lisp which supports JSON style expressions. DSLs are common in Lisp, and that actually became a weakness of Lisp (so-called "DSL hell"). The interesting thing about s-expr is that Lisp doesn't need special data conversion tools to handle them. Even control structures are expressed as s…

This is one of the most attractive things of lisp. The fact that the language has no notion of compiletime, evaltime and runtime. The user just doesnt have to care abouut it. Very powerful

This actually isn't true for Common Lisp.

There is a distinction between reader macros and compiler macros, for example, which is relevant for allowing using special syntax be optional for end users.

Certain things also need to be defined if you want them to be available in the compile-time environment. And, sometimes you have to do a bit of extra work if you want to have literal objects in your compilation environment and pass them to runtime.

Check out http://www.lispworks.com/documentation/HyperSpec/Body/03_bc.... though it will probably take you a few readings to make sense of it; I know it did for me.

But for the most part things happen automatically.

Re: JSON API

#118

Post by steveklabnik »

mahmoudimus wrote: post #46
wycats wrote: post #40

Earlier quoted context omitted.

The main reason was to unify patches to attributes with patches to relationships, which do require richer semantics. It also makes it really easy to add a compound PATCH (updates to posts/1/title, posts/1/rels/author, posts/2/body, etc. all at the same time) in a single format. Once I bought into JSON Patch for the rest of this stuff, I figured I may as well use it for attributes :)

Interesting, how can I get more involved with how this is going to shape up?

Here it is: https://github.com/json-api/json-api

Re: JSON API

#119

Post by ch0wn »

wycats wrote: post #100
steveklabnik wrote: post #96

Earlier quoted context omitted.

Yes, I want to reduce some of the MUSTs, or at least justify them more strongly. Right now they're based on what our running code absolutely needs.

Indeed. In my experience, looser requirements in this kind of thing just leads to tears on the part of client and server implementations. I'll happily reduce some of the MUST s to SHOULD s or MAY s if it makes sense for the communication channel to consider them optional.

That's great to hear. One particular example which I found needlessly strict is this:

    The request MUST contain a Content-Type header whose value is
    application/json.  It MUST also include application/json as the only or
    highest quality factor.
It makes sense for fully compliant implementation to have those headers, but they way I understand MUST here is that a server would reject any request without them.

Re: JSON API

#120

Post by dacort »

I was a little confused that an "author" rel would be retrieved from a "people" resource. Is there a way to define that author's are people other than the client knowing this?
Post reply on HN