Technical Steering Committee
February 28, 2018
Attending: Prasad Chodavarapu, Sascha Cohen, Joel Farrell, Jon Johnson, Valerie Smothers
The meeting will focus on concerns Sascha and Jon have about OData. These include vendor neutrality and language support.
Sascha noted that working with OData raised some concerns. They want to ensure that the api is accessible to the user base. Jon found it challenging to find explicit documentation.
Jon explained his goal was to put together an API doc example and more deeply implement one end point, The spec is clearly laid out, but he was never able to find anything easier than from scratch. Whether creating swagger documentation or an end point.
Joel clarified that Jon wanted to define API, define end points and json payload. Jon noted he could see how to do it conceptually, but implementation was where he was stuck. Joel noted no way to generate consumption code. Jon clarified there is a lot of consumption code out there. It's the ability to produce the data that is more difficult. Teh fact that he couldn;t find anything to generate documentation was also concerning.
Joel noted that Elcipse oji... he asked if Jon was an eclispe. Jon noted for Java and .NET, it would not be an issue. He is not proficient in those languages. Joel noted that Eclipse is the place he looks. There is an Eclipse program called Oji that would do modeling and documentation.He noted he could look at more. he was hoping Prasad and others would share info on models and documentation.
Sascha questioned whether the existing documentation and tooling were suitable and sustainable for this project. Jon is a standard example of the kind of developer that would implement, and he is encountering difficulty. The lack of guidance for PHP and other languages is concerning. Prasad commented that if you are using a different custom data model, you have work to do. Jon commented that in .net or SQL, it might be 150 lines of code, But for Ruby, it might be 2000 lines of code.
Joel noted that .net and java has examples in JSOn api. He asked about support for those languages for json api.
Valerie asked about a simpler approach that did not require either json api or OData. Sascha asked if it was events.
Joel commented that the drive to more sophisticated approaches like OData or JSON API was because of Queries. Also output. Things like paging and skipping. A lesser driver, certain relationships you have in output. Metadata. That would push us to something like OData. Queries and complex handling as well. Joel asked if this was a day 1 requirement: complex queries and large output handling. Jon noted it was for them - max, min, offset, and relationships. We can make those choices. He didn;t want other working groups to make different choices.
Joel noted that the first APIs coming out, what are their requirements version the second version? Can we be smart enough in designing v1 to not get in trouble with v2? Jon agreed we should design version 1 independently. Joel agreed there was value in keeping things simple when we are just starting out. he recommended thinking about next steps. Joel and Prasad will look into the OData environment in more detail for non-.net and java. Jon can look at the reverse in JSON API. The third thing would be for the working group to look at whether v1 can be done at a level of complexity that does not require these features.
Prasad noted that client side is something to consider as well. Clients consuming API is usually the challenge. There are more client libraries. We also discussed ease of documentation. There are different potential priorities. Joel we should look at ease of use in terms of availability of libraries and tools for client and server, for server, how you can document your api based on artifacts of design, and what help is there on server side to jump start implementation. Joel noted it may be up to us to help our implementers with implementation guidance that is general to the consortium. Jon noted that from a design perspective Valerie can ensure consistency.That can work fine. Joel noted that first one or two APIs, everyone is responsible for being in line, We can see which are coming up.