Over the last little while, I’ve grown increasingly disillusioned with Agile developments[^1]. That’s not to say I advocate using Waterfall or even any problems I have with the core tenets of the Agile manifesto; it just seems that any company that is purportedly Agile is either using it as a cover for an ad-hoc structureless process or is steeped in so many Agile tools and processes that it is hardly Agile at all anymore.[^2] Moreover, there is hardly any process for useful planning activities like UX Research (if it is done at all.) It’s no wonder so many APIs seem haphazardly planned and missing core features.

Nowadays, I tend to advocate psuedo-Agile development with a few formal planning activities. One of these activities I’ve been exploring these last few days is API definition. In the past, my APIs have been created in a very ad-hoc way: methods would be created as I went, with no prior thought. By the time documentation is written, it becomes clear that many decisions are made for convenience (I admit that I am often guilty of conflating my RESTful routes; GET is such a convenience sometimes. I have been getting better about this, though.)

Over the last little while, though, API design tools have grown in increased prominence. Apiary has raised millions in venture capital, and recently, I volunteered at PolyglotConf where a small session advocated the use of RAML. I spent the remainder of the weekend checking these tools (and Swagger as well) out, and it was an eye opening experience.

Even if you’re trying to be as lean and Agile as possible, here are a few good reasons to try out an API design tool:

  1. Design. What sets RAML and API Blueprint (from Apiary) apart from prior API design tools are their top-down approaches to API design– it can be so much easier to analyze and design an API when you’re thinking about the bigger picture of your application. It makes it easy to see re-occurring patterns and plan for code reuse, but it can also be extremely lightweight. Just hashing out a sketch of an API in RAML made me realize that I could eliminate a few methods and planned functionality, saving myself future work.
  2. Collaboration. Having a common API design language helps to facilitate working with others on an API, particularly if you’re in a distributed team. It’s extremely useful for when your API changes: the text format makes it easy to track ownership of changes, and you can also programmatically update your clients about changes to your API.
  3. Tooling. Although Swagger is a little more oriented towards being read by machines, any of these languages can be used to standardize automated tools. Can you imagine generating an AngularJS client based on a RAML document? What a dream.
  4. Generating API documentation. This was how Apiary was originally sold to me, and why I wasn’t interested in it at the beginning– I didn’t see too much of a reason not to just roll your own, particularly if you have other documentation systems in place. It can be pretty handy, though. It can be generated for different audiences: besides developers, you might find it handy to communicate the API to business stakeholders and marketing as well.

I’m sure I’m missing plenty of reasons to consider formal API design, but even these four reasons are enough for me to discourage on-the-fly API creation. Even an activity as simple as listing out your routes before development can have positive benefits for your application. [^1]: Even Dave Thomas, one of the original Agile signatories, proclaimed that Agile was Dead. I only partially agree, and I don’t understand why wouldn’t you have a conference on ballet dancing? Ballet is really hard; it’s not just an art. [^2]: At least this is the impression I’m getting from off the record conversations from other developers.