JSON API roadmap


#1

Continuing the discussion from Extending Ember Data States:

Some months ago, the JSON API effort spun up backed by the rails-api and ember-data folk. I’m excited by the promise of an interoperable standard and I’d love to help where I can.

The current state of the JSON API spec is too ambiguous to be implemented. Currently ActiveModel::Serializers and Ember Data are undergoing major restructuring based on lots of hard-earned experience. From comments I have found in various issue threads, it seems that JSON API conformance is a stated goal in these restructurings.

JSON API is a lofty goal and I am certainly not asking “when will it be ready?” Instead, what I would like to see is more discussion in the open.

There are quite a few questions in the JSON API GitHub issues page, but no authority to answer them. I would like to help turn the active discussion into some form of consensus, but there can be no consensus without involving the major players: Santiago Pastorino, Yehuda Katz (@wycats), Steve Klabnik, Brian Shirai, and others.

Now these are all very busy people. What can we do as a community take some of the load?


#2

Personally, I think some active discussion on the API side of ember development would be welcome.

Just thinking about the topic generally a couple thoughts come to mind:

1.) When dealing with backends it can get very specific and perhaps idiosyncratic. So having a universal API spec does seem like a tough problem to solve. Implementation details rule the day. But interfaces are what matter most here. The client does not really care if your backend code is written in Ruby, Javascript, Java, C, Go, Python or anything really. It just has to speak a reasonably consistent dialect of JSON.

2.) Because of the nuance of implementation details of interfaces and data it would be helpful if the community rallied behind creating examples that demonstrate the use of JSON API. It would also be interesting to see examples that don’t quite work for JSON API and evolve the understanding of why.

What I would love to see is the community build an end to end example of moderate complexity. Maybe something a little more involved than basic Todo app or Blog example.

Basically with a flow like this:

  • Spec of API interface for example app.

  • Set of tests with no implementation (all failing)

  • Ember Client Example that works with specified API

  • Specific Backend implementations that support JSON API standard and example spec. Written in different flavors: rails/ruby, node/js, django/python, symphony/php, etc.

I think showing that all together in a well documented case study could be a helpful resource to people trying to figure this stuff out.


#3

Thanks for phrasing it this way. I agree that we need a process to move towards consensus on resolving some of the ambiguities in the spec without biting off on more features.

I would be very grateful for someone to work closely with me to implement an Ember Data adapter for JSON API, and with Santiago on making it possible (or even easy) to emit JSON API from ActiveModel Serializers. This process will help uncover ambiguities and implementation difficulties, and could help feed back into JSON API.

It’s not a simple project, so it definitely would need to be someone with the time and experience to get it right, but I’d happily take the time to give the right person enough context to get the job done. Any takers?


#4

@wycats The success of all three projects is very important to me. I’ve contributed to them all over the past year and would like to take a role in ensuring that they all work well together. I’ve been preparing some PRs for the JSON API project, which I’ll hopefully submit this weekend, since I see some loose ends that need to be tied up in order for everything to work together smoothly. Let’s chat soon…


#5

I’ve been working with ember data and active model serializers on a reasonably large project for a few months, and the key things Ive had to solve in this area are;

  • polymorphic associations
  • lazily loading associations

As of 0.9 activemodelserializers no longer handles polymorphic associations, and jsonapi doesn’t talk about them

Lazy loading seems to be allowed by the url-form of json api, but I haven’t seen this implemented.


#6

Has anyone used ember-json-api? Might it be a good starting point?


#7

I’m don’t have the time to head up this effort, but I will absolutely contribute use cases, examples, tests, code review, issue management, documentation, and anything else I can. @dgeb, if you are going to take the reigns, let us know what we can do to help :smile:


#8

Sounds great, @samg - thanks! It obviously won’t all happen overnight, and will only be successful with input from developers with different perspectives and use cases. At the moment, I’m trying to distill a lot of the issues in JSON API down to PRs that are consistent and cohesive. I hope to have several together for review this week, so please keep an eye on the project and make sure that it’s going in the right direction for you.


#9

Interesting… thanks for the link. I hadn’t seen this adapter before. Since the ActiveModelAdapter in Ember Data itself is compatible with AMS, which will be compatible with JSON API, then we should see convergence between these adapters.


#10

I’d also be happy to help out in a similar way to @samg’s offer. I’m building a number of Ember applications backed by my RestPack::Serializer project and I’m keen to switch from my custom kludged Ember Model adapter.


#11

I can also provide assistance like @samg and @gavinjoyce. I would like to help nail down the format as well, as I’ve been trying to figure out the best way to perform batch operations for some time now and I think that is in line with the current structure of JSON API.

Should batch create/update/delete be included in the JSON API spec?

@matthewrudy: Why did AMS drop polymorphic associations? That seems like an important feature to drop (although I suppose they could just supply the model_id and model_type fields directly in the serializer).


#12

I just started a project using RestPack::Serializer along with ember-json-api. Had to made a small change to the serializer to handle the linked entities emitted from RestPack (and part of the spec.) So far it’s working just fine. Early stages though but we are using Ember Data and Ember 1.5.


#13

@nathanpalmer That’s great to hear. Are you interested in submitting a PR to RestPack::Serializer with your changes?