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

21–30 of 140 posts

Re: JSON API

#21

Post by wycats »

alexkcd wrote: post #16
calebio wrote: post #15

Earlier quoted context omitted.

I may be missing something, but how is searching an array of JSON objects more efficient than direct lookup by ID?

I agree with you. "OP" was referring to your suggestion. I edited my pervious comment to clarify.

OOP here. There are a lot of these kinds of decisions that need to be made for an API like this. In general, I went with what we're already doing if there was a toss-up. A big strength of JSON API, imho, is that it's an extraction from a real world system that a number of people are already using in some form.

It's important to note that the goal of JSON API is to be consumed by a general-purpose client (like Ember Data), so the JSON will likely be processed once and indexed as needed. In the system we extracted this from, the Array is loaded into a Store, which indexes the documents by type and id, so future lookups are quite efficient.

Re: JSON API

#22

Post by wycats »

ryanflorence wrote: post #17
1qaz2wsx3edc wrote: post #5

Earlier 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 if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`

OP here.

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!).

Re: JSON API

#23

Post by calebio »

alexkcd wrote: post #12
oinksoft wrote: post #8

Earlier quoted context omitted.

Ordering. The ECMAScript standard does not specify property enumeration order.

The related documents are indexed by id from the primary document, so ordering doesn't matter, and it makes sense to use a format suggested by calebio, as it's both more efficient and terse. However, the primary document and other nested entities which require ordering should return an array of objects. Edit: clarification

We did something similar to this alexkcd at Mavenlink using our Brainstem gem (you can see an example of the JSON at https://github.com/mavenlink/brainstem).

We generate a results array that is ordered based on the default order or supplied order. You can easily iterate over that then do direct lookups in the top level keys.

Re: JSON API

#25

Post by mahmoudimus »

The PATCH mechanisms seem like RPC to me. Having an operation that is passed in the payload, i.e. "replace", is awkward.

Why can't you just PATCH a resource?

    PATCH /resource

    {
        "src": "newvalue.png"
    }

Re: JSON API

#26

Post by 1qaz2wsx3edc »

ryanflorence wrote: post #17
1qaz2wsx3edc wrote: post #5

Earlier 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 if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`

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.

Re: JSON API

#27

Post by 1qaz2wsx3edc »

vyrotek wrote: post #20
1qaz2wsx3edc wrote: post #18

Earlier quoted context omitted.

GET /teams/search?homecity=los+angeles Wouldn't this be: GET /teams/los+angeles 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 pro…

Isn't this what OData is trying to establish? Quick intro video http://www.odata.org Query formatting documentation http://www.odata.org/documentation/odata-v2-documentation/ur... JSON representation documentation http://www.odata.org/documentation/odata-v2-documentation/js...

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.

So, yes, I guess, in some ways, more OData like.

Re: JSON API

#28

Post by wycats »

mahmoudimus wrote: post #25

The PATCH mechanisms seem like RPC to me. Having an operation that is passed in the payload, i.e. "replace", is awkward. Why can't you just PATCH a resource? PATCH /resource { "src": "newvalue.png" }

The `PATCH` mechanism is an HTTP verb (RFC 5789: http://tools.ietf.org/html/rfc5789) using a standard patching mechanism (RFC 6902: http://tools.ietf.org/html/rfc6902). Both are RFCs that seemed like good foundations to build on.

Re: JSON API

#29

Post by alexkcd »

wycats wrote: post #21
alexkcd wrote: post #16

Earlier quoted context omitted.

I agree with you. "OP" was referring to your suggestion. I edited my pervious comment to clarify.

OOP here. There are a lot of these kinds of decisions that need to be made for an API like this. In general, I went with what we're already doing if there was a toss-up. A big strength of JSON API, imho, is that it's an extraction from a real world system that a number of people are already using in some form. It's important to note that the goal of JSON API is to be consumed by a general-purpose client (like Ember D…

That's a fair point, but using arrays only where ordering matters adds nice semantics that can be used by a general-purpose client. Using a map for related documents makes it explicit that document entries are unique and unordered (it's implicitly assumed to be true in OOP's case).

In addition, you'll find that you're using an array at the toplevel only for the primary document when it is a collection, and for nested collections within documents (such as comment ids). Semantics that general-purpose clients can make use of.

Re: JSON API

#30

Post by wycats »

1qaz2wsx3edc wrote: post #26
ryanflorence wrote: post #17

Earlier quoted context omitted.

What if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`

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…

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.
Post reply on HN