Simon shares a new approach to building self-documenting APIs and how it’s changing the way technical and non-technical teams collaborate.
In twenty years of web development, every large IT framework I’ve ever worked on has been built out of many coordinated systems. That’s meant APIs – both for connecting disparate systems together, but also for sharing information with everyone else.
But building these systems was only ever half the task. Without documentation, APIs are usually ignored, or at least misunderstood, which is why equipping developers with API power tools to craft and explore them is so valuable. Enter my two current favourites: Grape and Swagger…
Grape, for sweeter APIs
Ruby allows developers to quickly build expressive code, and evolving systems like APIs benefit from that particularly. Grape is one of the most popular frameworks in this space, supporting rapid development of robust solutions that can exist standalone, or cohabit with other Rack-based frameworks (like Ruby on Rails).
Swagger, when your documentation needs to strut
Documenting APIs is the other half of the problem, and traditionally it’s a laborious and error-prone one. Luckily, Swagger is here to save the day, providing numerous tools to make this process less painful.The grape-swagger gem can introspect our Grape APIs and generate JSON representations of them, and the swagger-ui (see below) can turn that JSON into an interactive playground where anyone can learn and experiment. Long story short – Swagger is awesome!
From a collaboration perspective, one of my favourite things about Swagger’s interactive documentation is that anyone can poke at it in real time. It also reduces the cognitive load of testing by making verification easy for anyone to do, so both internal and external developers and even non-technical stakeholders can have a look around.
It’s not all perfect.
Grape’s an opinionated framework suitable for mid-level APIs – very simple or very complicated APIs would suit either a pure Rack or a hand-rolled solution better (respectively). It comes with validation and error machinery that may or may not suit your needs – YMMV.
As tech companies evolve, they regularly grow out of frameworks – and for us, Grape probably won’t be an exception. But for a small agile team with big ambitions, Grape, combined with Swagger, is right on the sweet spot of expressiveness and simplicity that allows us to make APIs that are easy to learn, maintain and share with the team.
Simon Hildebrandt is a web generalist passionate about usability, music and being a dad.