Provide JSON API support

[sdeleuze]

I create this feature request after some discussions and thoughts that happen after the JSON API in a Java Web Application blog post and on the SPR-13570.

JSON API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. Clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely. Why not use the HAL specification? is also worth to read.

Ultimately, the goal of this feature is to provide support for the client-side Javascript JSON API libraries, like the most advanced one Ember Data.

I am not a Spring HATEOAS expert, but my thoughts about that is that such support may be achieved by adding JSON API format support in addition to HAL, and providing standardized ResourceController/RelationshipController Spring MVC controller interfaces that may the the Spring couterpart of Katharsis ResourceRepository/RelationshipRepository. This last point seems quite important since JSON API is not just a format, and also defines standardized REST endpoints for dealing with CRUD and relationship operation. You can have a look to RESThub RestController for an example of such controller interface.

I have not the knowledge to contribute that support alone, but I will be happy to contribute.

[odrotbohm]

I am all in for being able to produce JSON API compliant output for ResourceSupport subtypes. However, it feels like the spec suffers quite a bit from feature creep (see the aforementioned Fetching) which makes implementing only the hypermedia aspects quite tricky.

I guess we can start simple and take it from there.

[masterspambot]

Just to mention @sdeleuze currently most advanced JS client is Orbit.js that has adapter for ember-data. It is maintained by the guys behind JSON API.

[sdeleuze]

@masterspambot Thanks for noticing, I was not aware of this one. It seems very interesting (and not specific to EmberJS).

[keithdmoore]

👍 for JSON API support

[dom-atom]

When we can expect the first release?

[masterspambot]

@dom-atom @keithdmoore Katharsis we already have Spring Adapter supporting fully JSON API 1.0 standard:
https://github.com/katharsis-project/

[amaltson]

👍

[donahchoo]

Is Katharsis a valid way to support JSON-API in Spring (boot)? I ask because they don't actually provide a controller and endpoints. They provide a filter that magically maps things to your model. It does appear to work, but it feels odd to not have actually endpoints. Additionally I have found an SO post that indicates it doesn't play nice with Spring Security.

Is there a way to use JSON-API with Spring-HATEOS instead of HAL? That may be more of what I am looking for...

Currently, Ember Data supports JSON-API natively and we are using Ember...

[gregturn]

There are actually several efforts in progress (I know it's been slow) to add some more mediatypes including Collection+JSON, Siren and Uber. I briefly looked at JSON API back when this issue was raised.

I'm quite aware of the popularity of JSON API in the Ember community. After we go through these other mediatypes, I feel we will have learned enough to make a better decision on JSON API and how to approach that as well.

[chb0github]

@donahchoo - I can answer your question about Katharsis but it's off topic here. Create and issue there or find me in the gitter room for katharsis.

[slinjhu]

I am looking forward to it.

[javac9]

I'm also using Ember (Data) and it's expecting that the response is fully-compliant JSON API as per the error I'm getting:
ember-metal.js:3987 Error: Assertion Failed: normalizeResponse must return a valid JSON API document: * One or more of the following keys must be present: "data", "errors", "meta".

Are there any news on the progress of things mentioned here?

[marceloverdijk]

Is there work done in this that can be shared? I would be interested to know the status.

[gregturn]

I poked at the spec a couple years ago and found it hard to discern where links should go. I haven't made any more progress on this mediantype.

I'm presently working on unifying my Collection JSON efforts from two years ago with our newly released Affordances API. After that it may be possible to revisit JSON API, though I'll probably push through Uber first since the work is mostly done.

[marceloverdijk]

No worries, was just wondering. After evaluating various hypermedia specifications.
I liked the clear flattened includes approach of jsonapi to "cache"/include linked resources.

[marceloverdijk]

But that said there are not many implementations for jsonapi resources in Java. Both http://katharsis.io/ and http://www.crnk.io/ look very similar (forked?). Both requireda to implement a ResourceRepositoryV2 repository which feels a bit weird. I was hoping there was some vanilla Java library for jsonapi just like there is https://github.com/otto-de/edison-hal for HAL.

[peavers]

@maciejwalkowiak While not exactly what you want, we have no issues using jsonapi-converter in our controllers to convert standard ResponseEntities (Of type String) into Json API Spec which Ember is happy with.

I have a very generic common library here which may or may not help.

[marceloverdijk]

@peavers thx for mentioning jsonapi-converter; it look interesting 👍

[vpavic]

Are there any plans to revisit this in the near future? Thanks.

[gregturn]

I haven't re-read the spec since last. I just remember it being awkward that links had two different places to go. Hence, I had to guess that perhaps one was for IANA-standard rels, and the other for custom user rels.

So we could revisit it if there appears to be enough community interest.

The real question is, since this mediatype appears heavily favored by the Ember.js community is, if we supported it would Spring HATEOAS becomes a more popular means for server side Ember apps, or would the community in general stick with nodeJS?

[peavers]

From my experience with Ember.js, the majority of the community use Ruby/NodeJS due to how simple it is in general.

The adoption of JSON API spec is growing and I personally would like to see it supported and used everywhere that isn't switching to GraphQL.

I know that I'd start using Spring HATEOAS in both personal and enterprise projects as everything I do follows the spec.

[vpavic]

Thanks for the feedback @gregturn.

So we could revisit it if there appears to be enough community interest.

The real question is, since this mediatype appears heavily favored by the Ember.js community is, if we supported it would Spring HATEOAS becomes a more popular means for server side Ember apps, or would the community in general stick with nodeJS?

Regarding the community interest aspect of the story I can share my current situation - we're involved in several projects with a reputable company that governs the use of JSON API. Backend services that implement JSON API are Spring (Boot) based, and consuming clients are diverse - Android, iOS, Angular, etc. There's no Ember.js involved here and I don't believe the situation I've described in unique - so while I'm personally not a big fan of JSON API I do share the sentiment of @peavers that the adoption of this spec appears to be growing.

At the moment we're using custom response factories that aren't pretty, and I'd definitely stick with Spring MVC for implementing these JSON API services as alternatives like crnk.io are not appealing. Spring HATEOAS feels like a natural place for this integration to happen in terms of Spring ecosystem.

I'd be also happy to contribute to this effort.

[lorenzleutgeb]

I might also leave a short note.

At the company I work for, we've been using JSON API with PHP (cloudcreativity/laravel-json-api) for some time. Clients libraries are primarily Node.js, but not Ember.js (e.g. twg/devour).
Just recently we were asked to implement an application with Java, and naturally we chose Spring to be our main driver. Naturally I started looking for solutions in this space.
It seems that the aforementioned project Katharsis is not maintained anymore, and I as far as I can see Yahoo's Elide and crnk both tie together the presentation layer with the persistance layer. I am having a hard time to integrate them with a business layer in terms of services. This is how I ended up here.

I have some experience with JSON API, since we implemented a solution similar to Elide in-house on top of the Laravel library. Happy to discuss, and also contribute in case there's small-ish and well-specified tickets to tackle.

[chb0github]

Katharsis is indeed, defunct. krnk.io is a fork of Katharsis Both suffer from an inflexibly tight integration between layers which is what made integrating security extremely difficult and dependency injection nightmarish. Basically, the whole stack derives from a Tomcat filter in the chain.

[atkawa7]

@gregturn PING

[gregturn]

At this stage, given our uptick in project velocity, I'd be willing to re-read the spec on JSON API and entertain crafting a set of serializers and deserializers provided the spec isn't too convoluted.

As for the other things mentioned in the history of this project such as how to form links, that I would rule as being out of scope.

In essence, just as we've added message converters that now handle HAL-FORMS, Collection+JSON, and UBER+JSON, adding analogous support for JSON-API sounds reasonable pending a revisit of the spec.

[ExpDev07]

Any updates on this? I am using Spring Boot and want my RESTful API to follow the JSON-API spec, as to be compatible with EmberJS's serializer.

[gregturn]

We’re in the middle of hammering out https://github.com/spring-projects/spring-hateoas/tree/feature/new-mediatypes, which will make it possible to develop additional media types.

JSON API would be a prime candidate to try this out on once this branch is merged to master.

[ExpDev07]

We’re in the middle of hammering out https://github.com/spring-projects/spring-hateoas/tree/feature/new-mediatypes, which will make it possible to develop additional media types.

JSON API would be a prime candidate to try this out on once this branch is merged to master.

Thank you for such a quick response! Project looks awesome and promising, can't wait!

[shi98013]

We’re in the middle of hammering out https://github.com/spring-projects/spring-hateoas/tree/feature/new-mediatypes, which will make it possible to develop additional media types.

JSON API would be a prime candidate to try this out on once this branch is merged to master.

I am following up on the progress of this.
That feature branch is gone now but it appears to me that it made it into the March 5th release of the spring-hateoas version 1.0.0.M1, https://github.com/spring-projects/spring-hateoas/blob/master/src/main/resources/changelog.txt, am I correct?

[odrotbohm]

Yes.

[gregturn]

Read here (https://docs.spring.io/spring-hateoas/docs/1.0.0.BUILD-SNAPSHOT/reference/html/#mediatypes.custom) and also look at the existing test cases as a road map.

[dziadeusz]

Hi, is there current work in progress to develop full support for JSON API like the one for HAL or do I have to develop it as a custom media type as stated above?

[gregturn]

There is a submitted PR at #969.

[gregturn]

Superceded by https://github.com/toedter/spring-hateoas-jsonapi and #1337.