search

uWaterloo / OpenData

Help and Support for University of Waterloo Open Data Initiative
https://api.uwaterloo.ca
90 stars 12 forks source link

v3 API violates Swagger/OpenAPI spec #201

Closed ianjfrosst closed 4 years ago

ianjfrosst commented 5 years ago

The Swagger 2.0 specification states that the operationId field of each of the operations must be universally unique:

operationId: Unique string used to identify the operation. The id MUST be unique among all operations described in the API.

However, most of the operations available in the v3 API use the same operationId of 'Get', which violates the spec and makes it difficult or impossible to use a generic Swagger client to access the API.

sbobkin commented 5 years ago

Thanks for the heads up -- I'll add ta task to correct the method/operationId naming in one of the future releases.

ianjfrosst commented 5 years ago

https://editor.swagger.io/ tipped me off to the source of the problem when my API client started throwing errors. The schema validator there seems to be pretty thorough.

sbobkin commented 5 years ago

Yea, the primary use of Swagger was the nice documentation and try it interface that came with it. Meeting the full specs was not a goal, but this should be something we can correct.

ianjfrosst commented 5 years ago

Would it be possible to open-source some of the API resources (like the Swagger configuration)? I know at least I would be interested in contributing, and it would make it easier to propose changes to the API & keep documentation updated.

sbobkin commented 5 years ago

We've had a brief discussion on open sourcing the API code, a decision hasn't been made. For Swagger we auto generated the documentation, https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=visual-studio from code/comments.

I think the biggest question for us is in the value of open sourcing the API code itself. It's 90% SQL with Dapper.net mapping to objects with data from the database. At the same time though, there is no reason not to release it in the future too.

There's a discussion coming up on what to do with what we call crowd data, that is data that has no clear authoritative source. Depending on the outcome of that, if an API is made to cover that space, maybe that's where we'll look for more contribution.

sbobkin commented 4 years ago

This took a long break, as did the rest of the progress, but I believe we no longer violate the spec.