MedBiquitous Technical Steering Committee
Attending: Sascha Cohen, Jon Johnson, Luke Woodham, Joel Farrell, Scott Kroyer, James Fiore, Prasad Chodavarapu
1. Discussion of the use of the JSON API spec in MedBiq APIs. We will be joined by our colleagues from UCSF.
Joel welcomed Sascha and Jon. he brought upthe possible use of the JSON API spec. He asked Sascha and Jon to talk them through the decision behind using JSON API. Jon explained they wanted to pick a standard so they wouldn;t have to make so many choices. It may not be the perfect solution for Medbiquitous, but picking something to reduce the choices would help to prevent "bike shedding," small changes to the API. They spent a day on pagination for results. JSON API makes that choice for you.
Joel asked if the nature of the API has a lot of collections/aggregates. Some of our initial use cases are very simple, like what is this person;s medical school. They usually don;t require such decisions, but collections that you have to navigate through might require more sophistication, which is what JSON API is targeting. Jon noted that they are definiing more than 20 endpoints that relate to each other in many ways. They need to be able to pull data form any of those places and get all the relationships. You may know the course or the user. If you have a simple API that provides a binary response, this would be overshoot, as long as the why behind a response is not required.
Joel asked if they were a strict implementer. Jon rpelied they are a strict implementer of 0.8. They will implement the new version next summer. Strict implementation makes certain things easier. MedBiquitous would not need to be strict.Joel noted the definition of unique content type was bothersome. jon noted that is just a header convention. Joel noted we thing we need the ability to support XML and JSON. We would support content negotiation. Prasad asked about the reason for using the new content type. Jon replied that his guess was that they needed to do something to get IANA assignment. It provides a way to flag for use of the standard. Joel added that it tells you that this is a JSON API compliant payload. You have to document your API. He clarified that they are only supporting JSON. Jon rpelied that they started by supporting XML and JSON, but no one requested the XMl document back, and HTML was only useful for testing, Dropping XML and HTML simplified. MedBiq is in a different category. XML and JSON are structurally similar, It is not horrible to support both. Joel noted that we don't require anyone to support both. There is nothing about JSON API counter to our direction. It's more than some people need. If you had a situation where you had these relationships, we would recommend JSON API to simplify the API creation. He added he is not a fan of the new content type; it doesn't say anything besides it's JSON. They have an error object that is similar to what we define, but it's a little different. Jon confirmed they are using the error object. Joel noted e would have to think about changing to be like their 1.0. Joel noted we likely don;t have id field. Jon noted they use status code, title, and sometimes detail. Joel noted we emphasized source. There is an input document, you can point right to the object with the error. Jon noted they will add that with full compliance.
Prasad commented, is there an API? What is the intention. Valerie explained that... Pr noted we could use Odata to do the same thing - it runs on top of many things. He noted OData is already well established. It does exactly the same thing. there are already systems built to understand that.jon replied that there is no difference. The important thing is to pick something. Prasad noted that he has looked at both. There are already systems using OData. OData has more traction. They just released version 4. Large organizations have chosen OData. Jon repelied that OData is more enterprise oriented, and JSON API more developer oriented. Other competing standards include JSON LD and Hydra. He guessed he could convert from JSON API to OData in weeks or months.
Joel asked about the relationship between Ilios and the Curriculum Inventory API. Jon replied they are different. Joel replied that Ilios APi is a curriculum API and MedBiquitous is informed by it. Sascha replied that Ilios is curriculum management API that communicates with the curriculum inventory. We are being informed by the Curriculum API as it is an exemplar. V replied early. Joel recommended the TSC look at this more closely. He asked for UCSF's implementation language. Jon replied PHP; they consume in java script. Joel noted we have a mix of expertise. Joel noted producers would be universities or societies with CME? V replied it depends on the working gorup. In Curriculum Inventory, the users are universities, curriculum managemen developers, ...
Jon noted that users interact with a web application that interacts with evalue. They pull data for learner groups. Sascha described it as a mature implementation point, but they are extending what they have and have a three year roadmap. Joel asked if there was anything about JSON API they were not pleased with. Jon noted it has been a while since they did that implementation. They had to wrap their heads around the philosophical approach. Joel noted that OData has a number of languages. Joel asked if there was a JSON API specific library. Jon replied no; they use a library for consuming API data. Filtering has turned out to be much more than querying. Prasad replied that when you apply filters in OData, it is complicated. Jon noted if you can get all the data quickly, there is no reason for the server to do the filtering, that can be done by the client.
Prasad asked if we should propose these as options. Joel noted we should discuss that. We need to point working groups at what they should look at. We could present it as a recommendation or a choice. how deep down do we want to go?
Sascha noted they don't see a problem with having multiple options as long as we can ensure they broadly meet the same guidelines. Jon noted they look to MedBiquitous for guidance. V noted that many groups lacked depth of technical sophistication. they would be grateful for guidance. Joel commented we might be able to do if this then this choice. We don't want to force a single option. We can continue to discuss and look at handling of error objects.
2. Publication of the updated security guidelines (sent out earlier by Valerie)
Joel noted last call we recommended changes to the guidelines. Copy is final - we can post to the website. Joel thanked Prasad and the committee.