API description formats

[Chris Weis]

One core part of Geekier APIs (https://github.com/rulesio/geekier/wiki) is a repository of API descriptions - not libraries - that are supposed to be processed by an api factory which will create connection objects from it.

Of those API description formats there are several out there that look interesting, for example, Swagger (https://github.com/wordnik/swagger-core), iodocs (https://github.com/mashery/iodocs) and the Google API Discovery Service Document Format (GADSDF - https://developers.google.com/discovery/v1/reference/apis).

While looking into all of those we also compiled a list of things we would want from this format. The most important to me are:
- A way to describe the authentication scheme (oauth, some token, you name it)
- Errors one should expect from a call (or the whole API), what they mean (i.e. a message to display to a user) and whether or not one should bother retrying
- The ability to describe the same call in more than one way (with static values for some parameters, ideally)

I'm currently thinking about extending the swagger format with those details but want to put this question out to there, so that you can weigh in with your opinions or experiences.

Let me hear, what you think, which format you like better, maybe, or which existing solution you think we should stick with.

--
Chris Weis

rules.io, Berlin

[Dan Applegate]

Thanks for putting this group together, Chris! My friends and I have been discussing how we would implement exactly this for a couple of months now, so it's good to see it taking off!

When thinking about creating a well-designed API, I found these introductory posts by Steve Klabnik and Peter Williams very enlightening. In them, Klabnik and Williams discuss using built-in HTTP headers like Accepts and Link to handle api versioning and resource discovery, respectively. In my mind, these methods would be much preferred to the mishmash of "standards" that a lot of API providers use to convey this metadata about their API. By formalizing the location for this metadata and removing it from the response body, you achieve better separation of concerns and a cleaner implementation.

I think whatever format we decide upon should have a way for these APIs to specify that their endpoints provide such methods for versioning, content negotiation and resource discovery.

Hopefully, with time and with a wider adoption of Geekier and its underlying API schema specification, we'll then be able to pressure API providers into using these best practices,  thereby normalizing the majority of APIs out there.

Dan

[Chris Weis]

Hi Dan,

sorry for responding to your post so late. I appreciate your perspective a lot - what we're trying to achieve is actually a format that can describe just about any HTTP-based API out there.

Making better use of headers could really be a thing and I hope some APIs will embrace it and show off the advantages that approach has. I'll definitely read up more on it.
Our immediate focus is on working with the 'mishmash' that's out there so that we can make everyone's life easier today. To make our format flexible enough to accommodate all those different approaches. And adding support for such header-based formats should really be a very easy thing, since those formats are very straight forward and easy to use, hopefully.

I'm looking forward to seeing where this all will be going in the future. The API world is really in motion right now.

--

Chris Weis

rules.io, Berlin

[Dan Applegate]

Welcome back, Chris! Hope you're feeling better.

I absolutely agree, first priority should be creating a format and library that can effectively handle as many of the varied APIs out there as possible. It will be a pain having to handle all of the different implementations of versioning and format support, but it's got to be done if we want wide adoption of Geekier.

Once we've gotten that under our belt and have the interest of some of the API providers, then we can begin integrating best practices like the effective use of HTTP headers.

Thanks!
Dan