How to get started writing an API spec

Yesterday, I shared why I think an API spec is beneficial, even if you don't have external users.

Today, I will share my approach to getting started writing an API spec. For the purposes of this article, I'm going to talk about writing an OpenAPI spec, because it's what I use, but the principles apply if you pick another format.

The first big question is tooling. There are many tools available to help you write a spec. Some are web apps, some are desktop apps. Some are free, some are paid. What should you choose?

Well, the specification is just a text file in YAML or JSON format (I use YAML), so my recommendation when starting is to just use a text editor, no special tooling. This will feel a little tedious at first, but I think it's critical to understand how the spec is authored.

How much of the spec should you write? Just pick one resource to start with, ideally something with a few endpoints. And be verbose, write things out explicitly.

As you go, update your feature tests to add API spec validation. For Laravel apps, I like the openapi-httpfoundation-testing package. This will keep you honest that your spec is accurately describing the requests and responses in your application.

Once that's done, now look at refactoring it to use references to reduce duplication. All the while, you can keep re-running your tests to make sure nothing broke.

With all that experience under your belt, now it's time to look at tooling to more quickly build out the rest of your specification. Being completely transparent here, I have yet to find a tool I really like, so I often just author directly in PHPStorm, which has nice OpenAPI support available with a free, first-party plugin.

Here to help,

Joel

P.S. If you want a jump start on writing and testing your API specification, I'd love to talk with you about your project.