Apipie-rails is a fantastic gem for documenting your APIs. Apipie also has some great features which will enable you to write better APIs. This post will discuss the basics of Apipie and how it can be used as a development tool for writing better APIs.
How to document your API endpoints
Apipie’s DSL can be added to each of your controller actions to document the endpoint and expected params. Here is an example:
api! 'Creating a User' param :user, Hash, required: true do param :first_name, String, required: true param :last_name, String param :password, String, required: true param :email, String, required: true end def create ... end
Initially I was concerned about putting these Apipie method calls all over my controllers. I was worried because, if my API changes and I forget to update Apipie, my documentation will be out of date.
On reflection, I don’t think this is a problem. There are two reasons why:
- Apipie’s DSL is not just for documentation, It’s actually adds validations. For example, let’s say you want to change your controller so that it no longer expects to be passed a region_id. When you run the tests they will fail, with a validation error, because Apipie is expecting a region_id. Apipie will also fail if a parameter has an incorrect type, in the example error below Apipie expected an integer but instead recieved a string.
Apipie::ParamInvalid (Invalid parameter 'id' value "15568746": Must be Integer)
- Strictly, your APIs should not be changing. If your APIs are changing frequently then perhaps you have a deeper problem. You should practice proper API versioning so that existing APIs are not changing. When you want to make a change to an API you create a new version.
Apipie causes you to write better APIs
Adding Apipie documentation retrospectively is a useful exercise in it’s own right. Where I think Apipie really shines though, is when it is used to define new APIs. I think it forces you to design your APIs properly. It forces you to decide each of the arguments that your API expects and the type of each of the arguments. For this reason, I think Apipie should become part of your TDD workflow for writing APIs…
TDD with Apipie
Here is the workflow that I am proposing, for integrating Apipie into the TDD process, when developing a new endpoint:
- Write a basic failing API test
- Add a route, controller and action to make this test pass
- Add Apipie methods to your controller, describing which params and types you expect. This will give you a failing test and a solidly defined API
- Update the test to pass the correct params
- Add test code to make the test fail for the response
- Update controller to make this test pass
Apipie documents your endpoints and adds validations. Apipie helps you structure your endpoints and should become part of your TDD development workflow. Apipie forces you to define your APIs properly by defining each of the arguments the API expects, as well as the type of each of the arguments.