API design using Apiary

It’s been proven time and time again how vital API documentation is to your developer experience. After all, in the world of APIs, developers are your users and therefore their experience matters most. In this blog post, we share what we’ve learned about API design and a tool called Apiary.

What is API design?

Designing an API is not just about the way you write the syntax, it’s also providing a powerful interface that helps the consumers of your API better understand and use it. Every product requires an instruction manual, and your API should not be an exception.

Let’s start off with comprehending the importance of why your API should have a great design.

Why does it matter?

Enhances Developer Experience

We’ve all experienced that one web service which had us stay up till 2am on Stack Overflow, scratching our heads trying to figure out just how to use it. A great API design makes the life of the developer easy. It’s quick to understand due to well organised resources, fun to interact with and easy to read, therefore developers consuming your API have an excellent experience.

Encourages better documentation

Documentation is vital for your API. It can either be the end developer’s best friend or worst enemy. In most cases, detailed documentation will be created only after the API’s resources are mapped out. Ensure your APIs are documented faster and will less errors by ensuring a solid initial structure.

What is Apiary?

Simply put, Apiary is a platform that uses API Blueprint (a markdown related syntax) to help you create the design of your API and generate the documentation, detect syntax errors, and even create a mock API, so you can start testing without having to write a single line of code.

Why MessageMedia uses Apiary

It’s important to understand and cater for the different skill level of developers that are accessing your API. For newbies, they often need an introduction to help put things into perspective and would likely be seeking “hello world” examples. For the veterans, chances are they are using the documentation as a reference tool and require step-by-step tutorials for how to do something specific.

Apiary makes it simple to address a variety of developers requirements. It provides a customisable template that allows you to add and group sections whether it’s a basic introduction to your API or a tutorial on how to construct a POST request, Apiary has you covered. Its intuitive interface makes it easy to navigate and understand what’s on the screen without getting overwhelmed. While you create the API, Apiary builds the documentation for you behind the scenes. The documentation is split into two columns – human and machine. The human half is what you would call an API documentation and the machine half is just a fancy name for a virtual console. The virtual console plays a major role in helping you prototype a mock API and using this console, a developer can test your API by sending mock requests and receiving mock responses. Apiary also syncs with Github which allows you keep track of the versions of your documentation as you continue building it.

Apiary Drawbacks

As magical as it sounds, it’s not a silver bullet. If someone has never used an API blueprint before and wants to use the platform, it could take them some time to get used to its syntax and how it’s written. Although, for anyone who is familiar with Swagger, this shouldn’t be a colossal challenge as the syntax and structure are quite similar. The other thing to note, is the entire API document is constructed into a single page. Yes, that’s right. If you’re not careful, this can quickly turn into a nightmare to edit or update. Especially if you’ve got a lot of resources mapped out in the document.

A final verdict

As an out-of-the-box solution, Apiary works well. There are some helpful features on the platform which can aid your efforts but it’s definitely not an antidote for bad documentation. Great documentation takes time and careful planning. We’ve got a range of API documentations that we’ve built using Apiary that you can view over here.

Continue reading...

Managing API documentation over multiple teams
Bec Martin
September 12, 2019
Your first Django project
Natalie Byrgiotis
July 08, 2019