Attending: Joel Farrell, Chair; Tom Creighton, Rob Chadwick, Kirke Lawton, Jon Johnson, Sascha Cohen, Valerie Smothers, Scott Kroyer,
1. Summary of previous discussion about the support of advanced API constructs
Joel noted that the architecture document provides a straightforward approach to develop RESTful APIs. The original use cases indicated we would have fairly simple APIs: yes/no, subset of information, etc. The Curriculum Inventory is more complicated. Sascha and John raised the question as to whether additional guidance was required: relationship between resources, metadata, filtering, etc. Sascha and John had used JSON API. We also looked at OData. We considered recommending one of those for more complex situations. JSON API is more of a grassroots effort; OData was a Microsoft IBM led initiative which went to Oasis and a version is now an ANSI standard. Partly for that reason we recommended using OData. As John started working with it, he encountered some difficulties. It's strong for Micorsoft and Java environments but less so for PHP and Ruby. We've done research, which is in item 2.
2. Review findings collected on http://groups.medbiq.org/medbiq/display/TSC/REST+API+notes (still being updated)
Joel noted none of the implementations are as strong as C# or java. There are ways to do it in other languages. It's easier to be a client in those languages, harder to be a server. e were also going to look at how JOSN API was in those platforms.
Jon noted he looked at is JSON API implementable and how easy to implement. He tried to implement and document in JSON API using PHP. As easy as it is to implement OData in .Net it is to implement JSON API in PHP. He couldn;t find an easy way to document the API for OData. He discovered most people don;t document linked data APIs. They are expected to be self documenting. Joel noted there is a way to use xslt to transform the output/metadata from OData to OpenAPI for Swagger. Jon agreed there are ways to force this. The way of documenting by end points is different form how Swagger expects APIs to work. Joel noted that we may be able to defer the question, Could we start out simpler so we don't need all the facilities defined by these two specifications? Jon agreed; in fact, we don;t need most of the facilities. If we need to filter, how should we do that. If we need to paginate, how should we do that. Joel commented he did a lot of reading, There are two ways people use the term filtering. One is in a query sense. The other is in returning a subset of the resource. Which did you mean? Jon replied both. In some cases they may want to leave out large text fields. Is there a way to ensure the same decision is made? Joel noted that due to the nature of the data, we should try to be as simple as we can. Jon agreed. the standards seem mature, but the adoption isn't.
Joel commented pagination shouldn't be complicated. It might be good to use something similar to one of the specs we looked at for filtering. Could we do a straw man design and look at it? Jon agreed that was a good way to move forward. If one person is picking offset or limit by, making sure we do the same thing. Joel noted we could add those decisions to the architecture document. Joel asked what the PAI is going to look like? Kirke noted if AAMC is going to put data about medical schools, and ACGME does about programs, finding all the programs sponsored by a a medical school, there should be a way to join that together. Joel asked if you want that to be simple for the caller.
Rob noted APIs can be self describing by providing links as part of the data that is returned. For pagination, could provide a link to get more. It can be part of the payload. That goes for identifiers as well. Program API may need to say this other implementation that should be considered. You could provide a link to that as opposed to a database id. that also helps to make APIs self documenting. Kirke noted FAIMER has data on every school in the world. AAMC has information on every medical school in the US. When you get data about U of Alabama, they could provide a URL ot more information. We are trying to make it coherent for consumers using both. Joel noted that was fairly standard practice. If back end application interacts through REST with another back end application, I may be happy with a large output. If I am part of a web application, I may want to limit what comes back. We should provide standard practices. It would be good to get examples from Sascha and Jon for Curriculum Inventory. Then we can make a decision about how to move forward and whether to include in the architecture document.
3. Reexamine requirements for advanced API constructs in V1 of upcoming MedBiq APIs
Joel asked about the timeline for Curriculum Inventory for API specification process. When would we likely see some examples? Sascha commented that looking at initial progress, we had three basic endpoints mapped out and a couple more not addressed. it doesn't take a lot of time when they have tome to spec them out. We could have key points in the coming months, before conference in May. We can have a handful of examples by then.
4. Decision or next steps
Joel noted we could look at these ideas at the face to face meeting at the conference. Kirke asked about the use case for the curriculum inventory. Valerie explained it is about integrating the educational ecosystem. Kirke noted he ran across an API where the request required pre-processing, The response would say check back later. When you checked back, you would get the final payload. Having that accounted for would be useful. Joel asked if that is because the data is archived. Kirke noted that if it is a custom request, it may take 15 seconds to assemble. Without a check back later note, it would time out. What is the pattern for handling? Jon agreed. Joel commented we would need to discuss.Valerie asked where he ran into it. Kirke responded in board game geek. You can harvest a catalog of the data. It may be a big payload, 5 mb. Assembly takes time. Jon noted in Ilios if you generate a report, turning it into the XML takes time. They do the same thing. Jon noted they provide a link where the data can be accessed when it is ready. Kirke noted as a first pass, either approach would work.
- For now we will not reference any sophisticated API for restful services like OData.
- We will keep things as simple as possible. We'll try out approaches and implement practices across MedBiquitous APIs.
- We will have examples to look at by the annual meeting.
Kirke added that if the program data happens expeditiously, we aren't waiting.