Can we declare support for only a JSON API?

[jrjohnson]

Right now we are targeting supporting XML/JSON with some HTML views in order to make it easy to learn the structure. However this adds complexity to our setup and may not have any real benefits. If we DROP support for XML and make HTML a nice to have extra we can focus all development efforts on creating a 100% compatible JSON api following the standards at http://jsonapi.org/
It is quite possible that we can do this with substantially less code by leveraging community work here:
https://github.com/gointegro/hateoas-bundle
or here
https://github.com/tobscure/json-api

By supporting a single API standard we can write more focused documentation and eliminate complexity in our code.

Since XML APIs seem to be a dying format dropping support may very well have no negative implications.

It will be much easier to add XML later as a supported format than it will be to support it in the 3.0 launch and then remove it in the future when it is under-utilized.

Thoughts @Trott and @saschaben

[saschaben]

I would be easily in favor of this but for one issue: the Curriculum Inventory Standard.

At the moment, the CI is an xml-only standard, and is also potentially going to be foundational in a lot of larger initiatives moving forward. This will impact us as we move into the development for our upload tools in may and june, as well as a lot of discussions going on now about parsing data using the XML output from the standard as a bridge between systems and institutions. Before we decide on this, I'd like to sift thru the ramifications and risks. It may well be that the smart route is to carve out our needs for the CI tools, and provide broader support later in the year or early next year.

Let's put this on the agenda for Monday, and make a decision as a group.

[saschaben]

it would also be great to maybe get some feedback/thoughts on this from @vpassapera.

If we do go this route, I want to make sure that we are choosing the right community project to leverage. We would need to talk about architecture and intent there as well.

[vpassapera]

So, a quick look at http://www.medbiq.org/sites/default/files/files/CurriculumInventorySpecification.pdf

let's us know, that as it stands, I don't think we meet that specification. However, adding support for it can be independent of the api or HATEOAS with the jms serializer annotations and probably a DTO.

I agree with HATEOAS as it's the future of services. The jsonapi standard already has support for it through the use of some context links (i'm not sure about actions but this is something that can perhaps be handled through the OPTIONS http request).

I have a personal bias towards HAL since it is format agnostic (both xml and json) but if not for the CIS then jsonapi would work since it is based on ember data.

The original hateoas bundle was fsc-hateoas (a developer that worked at a previous employer used to be a contributor @baldurrensch), but they have since been superseded by https://packagist.org/packages/willdurand/hateoas-bundle which relies on https://packagist.org/packages/willdurand/hateoas and both are based on HAL, however, a serializer provider supporting json api could be built (possibly based on the links @jrjohnson posted).

These bundles also provide out of the box support for atom XML specificiation as an alternative to Xml HAL (although i'd still stick with HAL for simplicity's sake)

Currently, there's really no right or wrong when it comes to a Hypermedia format. Just whatever fits the project and whatever the developers biases are. There are some that are more pupular than others but that's about it (and even those numbers seem elusive).

My two cents

[Trott]

I'm in favor of providing JSON and not bothering with XML.

If I understand correctly, the Curriculum Inventory Standard stuff in Ilios 2 does not use the API (because the API does not exist).

I have no idea if the plan is to change that in Ilios 3 or not. But there's no reason it can't consume JSON and produce XML. That would at least isolate the XML.

(Or is the idea that the API should produce Curriculum Inventory Standard stuff directly? That sounds ambitious to me, but hey, I'm not micromanaging development...er, I mean, following development very closely.)

[saschaben]

Three issues for the CI stuff and the API:

1. the standard is (in a forward thinking way) the route to data sharing and cross-platform information transfer for schools moving forward. Which means that there is a high potential for a desire to consume someone else's XML.
2. That being said, there is no reason we can't address that as a separate issue as implied by @vpassapera , or build a CI-specific XML loader (or XML-JSON converter) that would do the trick. At the moment all we need to be able to do is generate the XML as we do now, which isn't really the issue. The issue is that we are determining the shape of how we will conform to this requirement.
3. As we are beholden to have support for the standard regardless, I want to make sure we throw all the options on the table before committing to a path that precludes doing cool stuff with it for the community in the future.

And yeah, I know that isn't really three issues, more three vague thoughts, but at least we have started the conversation!

[jrjohnson]

Wow - this really feels like an RFC. Great discussion. Currently the CI stuff is not part of the API which is strictly for pulling Ilios data out of Ilios and writing it back in. The entire Curriculum Inventory process is really about attaching and organizing meta data and can be handled separately without it being an architectural pretzel. We will probably provide a service point to download the CI XML in addition to what is included in the frontend UI, but I don't think it needs to be part of this discussion.

It sounds like we have some consensus that XML can be ignored and we can focus on a JSON standard. I created an issue in @vpassapera's PilotBundle to start looking at the best way to do this in a way that will allow us, and others to take advantage (https://github.com/TheDevNetwork/TdnPilotBundle/issues/24).

[saschaben]

@jrjohnson if you think that the following issues which will likely be leveraging the CI XML in the future can be safely ignored in the API and addressed effectively as a separate issue, then I will concur:

1. The export report itself (duh)
2. injection/extraction of information for visualization
3. injection/extraction of information for comparison
4. use as a data transport and migration tool to/from the system

I'm not saying we need to build or immediately address these, but this is sort of the landscape of what the standard looks toward in terms of cross platform data management. It sounds like none of this need touch our API. I just wanna make sure no bullets are getting shot in our feet.

[Trott]

It seems to me like the CI XML is huge (in terms of bytes) and is more appropriate for download and processing rather than queries over an API. Of course, I am the most ignorant one on this thread about this, so my opinion is the least valuable. So of course I'm going to offer it! Whee!

[jrjohnson]

We're going to stick with our current REST implementation for now and go to json-api for v2 of the API.

[jrjohnson]

A new library which will greatly aid this effort:
https://github.com/neomerx/json-api