Galaxy: Swagger and friends for describing the API

Created on 23 Nov 2016 · 6Comments · Source: galaxyproject/galaxy

Latest Galaxy has a really nice XSD to describe Galaxy tools, which enhances the documentation dramatiacally, thanks again all people involved. Imho the next step is to improve our API documentation by using http://swagger.io and make it even more discoverable.

Currently we have a awesome documentation for

bioblend
API source code documentation
and a collection on the wiki

However, I think Swagger can provide a nice additional interface, where users can interactively try to API and get a feeling what is possible. Moreover, the Swagger provides a rich set of tools that we could use for free following this spec - maybe bioblend can even profit from this and semi-autogenerate bindings?

The specification can be found here: http://swagger.io/specification
An additional benefit could be that we could potentially get smoke-testing for free as well with this project: https://github.com/tarekziade/smwogger (experiment yet).

Source

bgruening

👍3 ❤2 🎉2

Most helpful comment

I think this is particularly relevant as we think about reworking the Galaxy client and UI. I think we should produce swagger schemas/docs for all of the Galaxy API. We should then use this with a webpack swagger loader to generate data models (as POJsOs) and API wrappers on the fly. Thus, we will ensure the swagger stays up to date (since Galaxy will not work without it) and save a lot of boilerplate code on the client.

For the new client, all access to the Galaxy backend should only be through these documented APIs.

jxtx on 11 Aug 2017

❤2 👍2 🎉1

All 6 comments

For the new client, all access to the Galaxy backend should only be through these documented APIs.

jxtx on 11 Aug 2017

❤2 👍2 🎉1

@jxtx I am new to this particular API-design-service, do we trust swagger to remain open/free/relevant in the years to come? Is there vendor lock-in risk? I have used apiary.io before for similar purposes (not for model generation, but for API design, testing, and mock interaction) and since Oracle bought it they are tightening their 'free tier' service.

martenson on 11 Aug 2017

@martenson from the github repo:

The OpenAPI Specification is a community driven,
open specification within the Open API Initiative, 
a Linux Foundation Collaborative Project.

https://github.com/OAI/OpenAPI-Specification

It is now called OpenAPI. So to answer to your question, yes. I think this will stay for a while and already got some traction in the Open Source community.

bgruening on 11 Aug 2017

👍3

@bgruening thanks, I also found out that the apiary format (api blueprint) still seems to be open and converter in between many open API formats exists

martenson on 11 Aug 2017

The GA4GH Containers and Workflows group is trying to decide between protocol buffers and swagger for API descriptions - there is a good document comparing them here https://docs.google.com/document/d/1TnSdJma2GY3EHezciFofVToFPidL8Qkhh0h5rW2zxng/edit#. My sort of default position remains that OpenAPI is still likely a very good idea - but some of the comments in there give me pause. It will good to see it in action.

Update: Even more information (link thanks to @willdurand) https://philsturgeon.uk/api/2017/07/20/my-vision-for-a-perfect-world-in-api-specification/.

jmchilton on 15 Aug 2017

I would like to propose GraphQL as an alternative. It allows creating more efficient queries, requesting data simultaneously from multiple endpoints. I commonly have to make enormous requests of the API only to filter out a relatively small subset of the returned data. It also lends itself to data federation given its ability to have a hierarchy of servers.