by Mateu Aguiló Bosch

Beyond Decoupling: The Inherent Virtues of an API

Fellow Lullabot Andrew Berry has written an article on why to decouple. If you do go this route, it’s because you’ve thought a lot about how to separate concerns. Content consumers are separated from content producers. Front-end developers are freed from the dictates of a back-end CMS. This article isn't about the separation of concerns, but rather what lies at the middle of all of these concerns— your HTTP API. In fact, you'll find that in a decoupled project the HTTP API provides not only the middleware, but also the middle ground. Let me explain.

The communication interface

One of the important things to understand is that an HTTP API is not just a way to expose your data or content from a CMS; nor is it a way to workaround the complexity of making views for the front end. An HTTP API is an interface, the clearly defined contract between two sides of a data transaction that takes into account the needs and limitations of both providers and consumers. Done right, information can flow freely from the content management system to the end-user through many channels. Done wrong, circular dependencies or poorly defined object schemas impinge upon the free flow of information. To enable this “flow”, we need:

  • A common language—a vernacular—that allows every actor in the system a voice. This language should not be restricted to developers. Product teams, project managers, designers, stakeholders, and so on will influence decisions about the API. These decisions may come through the content model, which is built on the needs of the business. The people making these decisions might not be technical. You will want to re-use the nomenclature from the content model in your API, so a front-end developer, familiar with the API, can have a clear conversation with a non-technical business stakeholder.
  • The delegation of responsibilities. When collaborating across disciplines it’s easy to generate friction. Decisions about the API will affect who’s responsible for what, and all sides will have a claim. For instance, pagination requires a tricky balance between front-end and back-end performance. Make sure to think about these areas carefully so everyone knows what they’re responsible for.
  • Clear goals for the API. These goals can be written in such a way that they form the basis for test-driven development.
  • Expectations to be set. Good, human-readable API documentation means that your front-end team can begin work while the back-end implementation of the API is still in progress. This approach provides iterative feedback to the API developers. The API consumers get to try out the API as it's being developed and quickly discover any gaps or design bugs. Everyone wins!

Defining the middle ground

Collaborating on requirements with other human beings is usually the most difficult component of a project. Machine-oriented description languages (JSON, YAML, and so on) are not languages we can use to speak to each other. We’ve just talked about the importance of a vernacular, but how do we put that to practical use? In his article “API Best Practices: Spec-Driven Development”, Mike Stowe writes: “One of the quickest ways to kill your API is to define the API in your code, instead of coding to its definition.” Document and define your API first. There are tools to translate human-readable API documentation to their machine-friendly counterparts. Consider Apiary's Blueprint format, or, for a more technical approach (that also introduces testing), explore postman, Swagger, or RAML. Too complicated for your stakeholders? Consider the esperanto of computer science: spreadsheets. The following caption shows an example of a Season resource being described using the Blueprint format.

Apiary editor

That documentation is then rendered by Apiary in a more human-readable way.

Apirary docs

Whatever approach you decide on, make that documentation—that definition—the system of record. That will prevent the troublesome spread of conflicting information via the ticketing system or your email inbox.

Having shared documentation among a big team will introduce the usual problems. Consider version control for versioning and diffing, communication channels for discussion and change notifications, and a permissions system that is flexible across each stage of the API design. Choose someone to set this all up. You will want someone to draft a first approach for everyone to build from. This person may then become the gatekeeper if you decide to have one. GitHub, BitBucket and other web-based user interfaces for Git are good solutions.

The inherent virtues

Building from an API places decisions in the middle ground, avoiding favoring one specific team while also compartmentalizing the decision scope. This minimizes the probability of the ripple effects of a decision disproportionately affecting the API implementation or its consumers.

An API, like a contract, shields both parties.

There are many reasons why you will want to build your next project to be API-centric. When it comes to what the needs are and how to communicate to all the stakeholders involved, you want everyone to have a common language to express their requirements. This enables us to use our documentation tools and communication interface to implement each requirement in the API. When making technical decisions, your entire team will be able to effectively communicate using the API as a natural interaction point, reducing conflicts and helping to get your project out the door.