New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace Cliquet protocol by JSON-Api spec ? #254

Closed
leplatrem opened this Issue May 7, 2015 · 7 comments

Comments

Projects
None yet
6 participants
@leplatrem
Contributor

leplatrem commented May 7, 2015

Yesterday I assisted to @steveklabnik talk about the JSON-API spec at APIdays BCN.

I was amazed by the number of intentions we have in common! And, although we completely ignored its existence, the protocol we designed for Cliquet almost matches their spec! That's icing on the cake :)

Shared goals:

  • save the developers the hassle of making choices when building a JSON-API;
  • convention over configuration;
  • simple thus loosely coupled; (not like a couchdb protocol)
  • easy to debug;
  • pagination/sort/filter;
  • simple JavaScript clients (Ember data will support it natively in the next version);

Protocol differences:

  • so far Cliquet doesn't manage relations between models, so we'll just ignore their work on that for a start;
  • the Bulk API is different, and does not look like ours;
  • we have a simple concurrency-control model, and that could become an extension (like Bulk);
  • we have conflict responses regarding records field unicity;
  • the use of a dedicated mimetype is kind of overkill, but we could also serve payloads as application/json;
  • the pagination querystring param format differs a bit;
  • the sort querystring param has + for ascending order;

I strongly believe that we should put some efforts in adjusting our custom protocol to conform with the JSON-API spec.

Thoughts ?

@leplatrem leplatrem added the question label May 8, 2015

@almet

This comment has been minimized.

Contributor

almet commented May 8, 2015

Some notes while reading the document:

  • I don't understand fully how this specification is different from some other ones (which tend to have a more sementic approach)
  • Pagination seems handled with links, where we were using headers, and indicates when it's the "last" page (which we purposely don't do)
  • It seems that the records are not returned "as is", but rather in an "attributes" object. Why not but it seems it also could add parsing overhead on the client side?
  • I haven't found information about their batch endpoint.

That being said, I think it would be good to have a formalism on the APIs we're exposing, and if this is already being discussed elsewhere, then we definitely should consider it rather than doing or own.

@almet almet referenced this issue May 8, 2015

Merged

Improve new comer docs #247

2 of 2 tasks complete
@leplatrem

This comment has been minimized.

Contributor

leplatrem commented May 8, 2015

I don't understand fully how this specification is different from some other ones (which tend to have a
more sementic approach)

That was my question to @steveklabnik after the talk. He explained that most hypermedia initiatives tend to focus on semantics. JSON-LD tends to be like Semantic Web, collection+json tends to very good for search results, etc..

I haven't found information about their batch endpoint.

http://jsonapi.org/extensions/bulk/

@hiromipaw

This comment has been minimized.

Contributor

hiromipaw commented May 8, 2015

I see you have already opened a discussion about this.
My reference on #247 was only regarding an example of well known patterns.
I simply think each hypermedia type has their own standards and with time more standards will simply arise. So sometimes it is about picking a standard to use that looks appropriate for a certain project.

@steveklabnik

This comment has been minimized.

steveklabnik commented May 12, 2015

Hey all! Been reading this thread, would be happy to answer any continued questions. Here's some answers to the first ones:

I don't understand fully how this specification is different from some other ones (which tend to have a more sementic approach)

As @leplatrem mentions, each type sort of picks some use case they want to be good at. For example, HAL is an experiment in minimalism. Collection+JSON is trying to be the spiritual successor to ATOM. JSON-LD is taking the semantic web approach.

JSON API's tagline here is 'transferring objects over the network boundary,' like is common in many SPAs. I have a blog, it has Posts and Comments and Authors, I want to CRUD with them over the network from some sort of client. While we consider the SPA case specifically, this is something many non-JS applications do too.

Pagination seems handled with links, where we were using headers, and indicates when it's the "last" page (which we purposely don't do)

Yeah, we went back and forth, but ended up with them in the body. You can leave off last if you want to, or at least, you should be able to, I didn't double-check before writing that 😄

It seems that the records are not returned "as is", but rather in an "attributes" object. Why not but it seems it also could add parsing overhead on the client side?

Imagine you have a blog post (sorry, my Rails background makes this my go-to example all the time), and, to save network traffic, you want to request both the post and its comments in one request. You have to split out which things are posts and which things are comments. By keeping the same structure in the single case, you pay a tiny overhead in stuff to parse, but drastically simplify the logic of parsing.

I haven't found information about their batch endpoint.

It's an extension: http://jsonapi.org/extensions/bulk/

@Natim

This comment has been minimized.

Contributor

Natim commented May 12, 2015

you want to request both the post and its comments [...] You have to split out which things are posts and which things are comments

Well in my understanding not really because in that case comments are an attribute of the post.

{
  "id": "post_id",
  "title": "My blog post",
  "comments": [
    {"id": "comment-1", "text": "Here is my comment", "author": "natim"},
    {"id": "comment-1", "text": "Here is my second comment", "author": "natim"}
  ]
}
@steveklabnik

This comment has been minimized.

steveklabnik commented May 12, 2015

You could do it that way, but that's not the standard way. See the example on the homepage.

Embedding like this comes at a cost: while in your example, the author just has a name, but if there's more information, it gets repeated over and over. By pulling them out, it gets de-duplicated.

@hiromipaw

This comment has been minimized.

Contributor

hiromipaw commented May 12, 2015

I +1 what @steveklabnik said :). Also in a RESTful world Comments would be another resource that you do not necessarily want to consider as Post attributes.
Otherwise in comments you might think to also include the authors, and even their relationships, like friends or followers, and so on down the chain...

@leplatrem leplatrem modified the milestone: 2.0 May 13, 2015

leplatrem added a commit that referenced this issue Jun 3, 2015

leplatrem added a commit that referenced this issue Jun 3, 2015

@Natim Natim modified the milestone: 2.0 Jun 16, 2015

@leplatrem leplatrem added the protocol label Nov 26, 2015

glasserc pushed a commit that referenced this issue May 20, 2016

Merge pull request #254 from Kinto/fix-pool-size-production-docs
Fix deprecated pool size option in production docs

@tarekziade tarekziade closed this May 24, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment