APIDoc is a REST API framework that you can use to document your endpoints, generate services and client libraries, and so much more. Similar to Swagger, a well-known REST API framework, APIDoc attempts to be simpler, more flexible and more easily extensible than other API frameworks.

The project itself originated from the the Gilt technology organization and has been worked on by developers from different teams. They found that by spending more time on the design of an API and using standardized generated client libraries, they were able to save time on building the services. They did consider other frameworks available on the market such as Thrift, Swagger and Apiary but couldn’t find one which met their key requirements.

The project goal is to enable code generators to create native clients, which is an extremely rare feature and a huge benefit of using APIDoc. It doesn’t simply offer code generation but also native SDKs that are so efficient developers aren't required to write their own. Needless to say, the time saved leads to a team of happy developers.

Movio has invested heavily in APIDoc over the past year, during which we’ve also been building public REST API’s so that clients can integrate directly with us. In this blog I will outline how APIDoc has helped us develop faster and the main benefits we've seen as a result.

What are the benefits?

Potential benefits you can get from APIDoc can be huge, depending on how much you’re willing to invest in it. By using it only as a documentation tool, you probably won’t see many of the benefits as there is no direct link between your API and documentation. But you start to see the benefits by using APIDoc to generate the client code libraries (including the models used in your REST services) in addition to the documentation; it enforces a hard link between the documentation and API as they are both being created from the same centralized place.

Out of the box APIDoc provides you with a UI for displaying the documentation of your API’s which you can share with anyone that wishes to use them. APIDoc can also generate client code libraries written in Go, Java, JavaScript (ES5 & ES6+), Ruby, and Scala, as well as clients for specific REST frameworks. This functionality can also be extended in order to generate more than just client libraries if you wish, making the possibilities truly endless. It also brings more consistency to your code as it’s all generated from the same template.

These clients can be used for internal development or shared with anyone integrating with your API. This means you don’t have to spend time writing or maintaining libraries to support different languages and frameworks; they’re all generated for you and can be regenerated any time you make changes to your API specification.

You can even take the generators further and generate the code to power your REST services. This is something that we’ve accomplished at Movio and use a Play service generator to generate the REST services for our most recent public APIs. This has saved us a lot of time when it comes to creating a new API and has allowed us to focus on the shape and functionality of the API. This has been a key reason as to why we’re able to design and deploy a new REST service in the same day, which has been a goal of ours for some time now.

How APIDoc works (technical) and why it’s not so scary to use

APIDoc has two main tools: API documentation and code generation. Both tools read the information they need from the same place, which is commonly referred to as the ‘spec’. The spec contains everything that’s required to build and use your API; from documentation to models to endpoints, as well as everything in between. Instead of documenting your API by hand, you create the documentation from your spec, enforcing a tight relationship between your API design, code and documentation.

As APIDoc targets the microservice architecture it makes sense that it, too, is implemented using a microservice architecture. Each code generator is its own microservice which can be added to any instance of APIDoc. Code generators are also incredibly flexible and simple to implement; you’re not restricted by a language or framework like you are in many other similar tools. Instead, all your generator has to do is parse the JSON spec from APIDoc and respond with a generated set of files. APIDoc imposes zero runtime dependencies which allow you to maintain the way you write production source code and avoid risking uptime or performance in any way.

This helps to remove a lot of the hesitation from developers who have been burnt by code generation. Normally, the issue is that the code generators are too generic or abstract. Generated code often requires additional processing to be useable. APIDoc doesn’t try to tailor to everyone’s needs out of the box, but instead encourages the development of your own code generators, either by creating completely new generators or adapting existing ones. This is what we have done at Movio and haven’t yet run into a limitation imposed by generated code. We’ve had to make minor adjustments along the way, but have now saved countless days of dev time by generating code via APIDoc.

How does Movio use APIDoc?

We started off just using APIDoc to generate the libraries (models) and JSON serializers/deserializers for our REST services, after a few months we were generating Play services. This allowed us to really drive the design of our APIs from a JSON spec and focus a lot more time on getting the design and documentation correct.

Currently we generate the following:

• Scala model classes (libraries)
• Scala Kafka 0.8/0.10 consumers and producers
• Scala Play JSON serializers/deserializers, client libraries, routes, services, controllers and error handlers
• Scala Samza serdes
• JavaScript Redux Sagas

We have open-sourced all the generators we use, which you can find on GitHub here and here (most of them have been adapted). They should give you an idea of how the generators work and demonstrate how they can be implemented in different languages. All the code we generate and generators we use are also tested, which is a nice addition and gives us a lot more confidence in the code we generate and changes we make to generators.

We develop the generators in the language they’re generating code for, as we feel that it makes the most sense. It also means that it’s more likely the people using that generator can adapt it if they need to.

One of the big things that we didn’t like about APIDoc was the UI. While it was fine for internal use, we weren’t happy providing our API documentation via APIDoc to our clients. We decided to develop a fresh new UI for APIDoc that looked professional and was easy to navigate. Thanks to the microservice architecture of APIDoc, building the UI was relatively simple and clean and the APIDoc REST service helped to ensure we had all the data required to do so. We plan to continue development on this UI and are working on getting it merged into the official APIDoc GitHub repository.

Conclusion

So, if you want to save countless hours pumping out the same boring lines of code with minor changes, then give APIDoc a try. I’d highly recommend having a look through some of the GitHub repositories I’ve linked - especially the code generator ones - and try adapting an existing generator to suit your needs. Since everything is generated from a specification, the time and effort saved more than outweighs the time you invest in planning your API upfront.

Find out more about joining the Movio Dev Team.