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

51–60 of 140 posts

Re: JSON API

#51

Post by akamel »

wycats wrote: post #48
akamel wrote: post #47

Earlier quoted context omitted.

:) yes i'm very familiar with it...

And [this][1] looks similar to JSON API to you? [1]: http://www.odata.org/documentation/odata-v2-documentation/js...

The format is not identical! I was looking for a philosophical comparison between the standard (odata) and jsonapi; I am not seeing much more than a simplified response format (a transform really).

Was hopping to see something more substantive in a comparison other than: 'results are returned under "d" instead of directly "posts"'.

Most project need to answer the simple question of 'why?' - 'why do I as a project exist'; jsonapi.org's is full of 'Ember'; hence why my original comment hinted that it should possibly be called 'emberjsonapi'.

If this is intended to be generic; it should ditch references to Ember and instead refer to similar standards; explaining 'why?' it is better than them.

By all means if your intent is to make a more elegant standard (again comparing to odata) then that's a worthy goal. Stating _that_ will help your 'consumers' understand what they are getting

edit: clean up

Re: JSON API

#52

Post by steveklabnik »

1qaz2wsx3edc wrote: post #5
steveklabnik wrote: post #3

Earlier quoted context omitted.

I am literally sitting on a plane right now, but as soon as I get off, will be registering this type with IANA. So that helps #2. #3 will be do-able I think. I'm interested in this too. #1 is something that needs a good answer, yes. I THINK it's out of the scope of this, as there are already registered REL values that handle this, but we should clarify. I will be happy to answer anyone else's questions after I land,…

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 think that's particularly important either." Constructing your own URIs is against the very spirit of REST. Let the server do that for you.

Re: JSON API

#53

Post by steveklabnik »

rglullis wrote: post #13
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.

Things bothering me in this proposal: the need for the relation; the use of "posts/1,2,3" to represent a list of resources; the "resource template". None of these are needed with REST/Hypermedia. I've been using djangorestframework, and one of the things that I love about it (instead of tastypie) is the "Browsable API" renderer/parser mode. It's an excellent way to see if your API makes sense: if I'm not able to disc…

I'm sorry, I'm very confused here. Why does hypermedia let you get rid of link relations?

How is a 'resource template' different than a hypermedia control in HTML?

Why does the URI format matter? It's hypermedia, that's basically irrelevant.

It seems you want a "REST"ful API, and that's great. Build that. But then why the first sentence being seemingly upset with some sort of lack of imagined hypermedia support?

Re: JSON API

#54

Post by steveklabnik »

rcsorensen wrote: post #7
steveklabnik wrote: post #3

Earlier quoted context omitted.

I am literally sitting on a plane right now, but as soon as I get off, will be registering this type with IANA. So that helps #2. #3 will be do-able I think. I'm interested in this too. #1 is something that needs a good answer, yes. I THINK it's out of the scope of this, as there are already registered REL values that handle this, but we should clarify. I will be happy to answer anyone else's questions after I land,…

I worded #2 really, really poorly. 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 compl…

> I'd love to see a spec for how to search a collection against an API that is jsonapi compliant.

I would imagine they'd use OpenSearch in some form. Not 100% sure yet.

> The base URL for search is different for different API producers.

You've hit upon the reason why this needs to not be ad-hoc anymore; a few dozen ways of searching isn't good!

Re: JSON API

#55

Post by steveklabnik »

jeffamcgee wrote: post #35

The twitter API originally used pages, but they realized it was a mistake: https://dev.twitter.com/docs/working-with-timelines . The way the facebook API does it is a lot more sane: http://developers.facebook.com/docs/reference/api/pagination... . I think that you should specify the format for cursor based paging of resource collections. One way to do it would be to require a url to get more results: { "posts": [...]…

Currently, we don't say anything about searching. That's really an application-level concern, not something that needs to be in this spec.

(So you'd define your own rels and use them, doesn't affect this level of abstraction.)

Re: JSON API

#56

Post by steveklabnik »

pserwylo wrote: post #9

This is important. We've just been implementing a SOAP interface to our software, and have been discussing the best way to provide a JSON API using the same mechanism. The sticking point is probably that there is no standard way to define an API like there is with SOAP. One question though: I notice that the language they use if very similar to a typical RFC. Is this an RFC? and if not, why? I'm a little naive about…

1) I'm assuming this is Poe's Law trolling about SOAP. If not, then I apologize, but I'm not sure I can assume good faith on this one.

If you're not, then this is significantly different than SOAP, so no, this isn't what you're looking for.

This is not an RFC. It may eventually become an internet-draft and then (hopefully) an RFC.

Re: JSON API

#57

Post by steveklabnik »

eranation wrote: post #11

This is great, but I can't seem to be able to find the NoSQL flavored support. Seems great for relational style data models, but (I'm sure I'm missing something) I didn't see support for full nested document models. Did I entirely miss the point?

The implementation detail of "SQL or NoSQL" should not bubble up to your API. The data store you use is totally irrelevant, that's the entire point of encapsulation.

Re: JSON API

#58

Post by almost »

I think it's great that we're talking about standardising how we build RESTful JSON APIS. However I don't think this has got it quite right yet.

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? Why complicate the data format and require all that extra logic and gzip would remove most of the redundancy before transmission anyway?

Also the name is a bit of an annoying land grab. It'll make it hard to talk about JSON APIs without getting them confused with JSON APIs that specifically use "JSON API".

Lastly, it really seems based on a rails active record style data store, it's assuming ids are the most important thing and that links are all relations that point to other objects within the system. Proper hyperlinks and point anywhere and can link together disperate systems which don't necessarily all use the exact same formats.

Re: JSON API

#59

Post by wycats »

akamel wrote: post #51
wycats wrote: post #48

Earlier quoted context omitted.

And [this][1] looks similar to JSON API to you? [1]: http://www.odata.org/documentation/odata-v2-documentation/js...

The format is not identical! I was looking for a philosophical comparison between the standard (odata) and jsonapi; I am not seeing much more than a simplified response format (a transform really). Was hopping to see something more substantive in a comparison other than: 'results are returned under "d" instead of directly "posts"'. Most project need to answer the simple question of 'why?' - 'why do I as a project exi…

The references to Ember are in the introduction only and provide some historical context for the project. I believe that it's important for standards to come out of real experience, and that the context of that real experience will help others understand the goals. That's why I provided the historical background.

JSON API's design is based around a smart client that wants the ability to avoid making unnecessary requests for documents it already has, and to provide a format that avoids unnecessary duplication in compound documents. It also aims to be relatively easy to implement, both on the client and server, using tools and frameworks that are already widely in use using familiar idioms.

Re: JSON API

#60

Post by bitcracker »

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, "comments": [ 5, 12, 17, 20 ] } } }

LISP: (posts (id 1) (title "Rails is Omakase") (rels (author 9) (comments (5 12 17 20))))

Post reply on HN