When it comes to API design and the Swagger (OpenAPI) Specification, there are few people that have the level of passion as Arnaud Lauret, best known as the API Handyman (@apihandyman). Arnaud has worked in IT banking for almost 13 years — as both a programmer and project manager — and today, works on API projects and governance as IT architect at AXA Banque.
In September, Arnaud released the API Stylebook, which aims to help API designers solve API design challenges and build API design guidelines by providing quick and easy access to selected and categorized resources. Arnaud is the also the creator of a 10-part Swagger tutorial on writing the OpenAPI specification. His tutorial is a valuable resource for anyone that’s getting started with the Swagger open source tools, or SwaggerHub.
Earlier this month, we had the privilege to welcome Arnaud for our API Expert Panel: Developing an API Strategy for 2017 at SmartBear HQ. Prior to the panel, we sat down with Arnaud to learn more about his experience of getting started with Swagger, and common traits of good API design.
Could you talk about your experience of getting started with Swagger?
A few years ago we started an API project and we wanted to have documentation for our API, so we started to use the Swagger annotation to generate documentation from the code. I was not aware at that time that behind this annotation was a format — the OpenAPI specification. The initial result was not really OK because we did not give enough instruction to the developers who write the annotation, so the result was not really usable as documentation.
It was at that time that Swagger 2.0 came out — with a new specification, the editor, and the use of YAML. We needed to update our documentation, which was really complex because the documentation was in the code. So I started to play with the format by retrieving the existing generated documentation and convert it to Swagger 2.0 and I realized it was really easy to parse and manipulate.
I created another module which corrected many of the issues there were in the documentation. That was what triggered my envy to work extensively with this format. I had the sense at that time that we could do many, many things with that. We started by writing the specification with the OpenAPI specifation format. We planned to write some controls during design time, just by parsing the specification to see if the newly designed API conforms to our guidelines — if the new documentation is complete, if there is description everywhere…
It was step by step, discovering a new thing day after day. Eventually, I ended up writing a 10-part tutorial on my blog. The most important thing about the specification is that it’s really simple and you don’t need any complex things to parse it and do things with it.
What are some of the common design traits/guidelines you see in REST APIs?
All of the guidelines are really focused on — okay we want to do a REST API — what is a REST API? We have resources, we have to use HTTP protocols, the right HTTP status, and so on. They tell the story differently but they all explain the same thing in the same way from a very technical point of view. And it struck me when you asked this question, they do not talk about the real problem — how to see if an API as offering functionality. And not just offering resources with the HTTP protocol. We must have these kind of documents because we need to put the frame around the API design from a technical point of view.
But I also think all companies that need to design APIs, need functional guidelines how to design APIs from a functional point of view. There are books that talk about that but all of these guidelines are really technical.
Interested in learning more?
Stay up-to-date with Arnaud's latest resources of the APIHandyman Blog. Getting started with the OpenAPI Specification? Check out our OpenAPI resource section here.