Child pages
  • 2018-02-28
Skip to end of metadata
Go to start of metadata

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 added a concern was that while there are clear tools and documentation available, it is a slender selection of languages and platforms. He is hesitant to recommend something that requires a microsoft platform and java or .net. Many of our users are not in that world. Joel agreed we should not be tied to a platform or vendor. There is a set of things they talk about on OData, javascript, c++, python. He tried to find what else was out there. There are several language implementations. They are not all extensive. Some are very basic. They have Ruby and PHP. he didn't look for R. Jon noted he didn't find a Ruby or PHP implementation. He would be happy to look at those. 

Joel summarized that we want to be platform independent and support a reasonable number of languages. One of our principles is to base standards on other standards. That was one of the motivations for OData. If we can't work with OData, we can drop back from it. If we can, it has the advantage of being a standard. Jon clarified that they are a PHP and Javascript shop primarily.Joel noted that PHP is a top language; he knows that there are others in the consortium who use .net, java, or python. Joel asked Prasad about tooling for creating the data model. Prasad noted that they have used Swagger. You can usually see that along with the data model. Swagger is not specific to .Net. Jon noted that he was not able to find examples of OData Swagger documents. Prasad noted it is a document API. There is code reading his csharp code and generating on the fly. Prasad noted that when you describe your method in swagger, it comes into the documentation. Prasad noted there is a swagger PHP on GitHub. Jon noted the issue is generating OData api documentation in Swagger. Prasad noted that when they use OData, they specify certain methods that translate into Swagger parameters. .Net definitely understands OData. He will double check and update Jon. Joel clarified that it is PHP outside .netm using Swagger. Jon added OData outside of .net using Swagger. Joel noted Java would do that in the eclipse environment. Jon commented the eclipse plug in had not been updated in 2 years, and it is marked 0.7. He would like to see some working implementations to leverage. There isn;t something to start with. Starting from scratch is a tough proposition.  Prasad noted that you would still have to map the query to the underlying data model. 

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.

  • No labels