Building your API Early

Author:
Brian Stanwyck

Tweet

In an increasingly multi-platform web—full of iPhone and Android apps, social media plug-ins and other third-party developers—building your API first provides unified access to an app’s data. In standard processes you might, for example, build a web front-end in Rails, then later need a phone app that can access and update the same data. An API built as an afterthought can lead to an ad hoc “gluing” of functionalities together, rather than providing the cohesion across platforms that a well-planned one provides.

Defining functionality early

From the developer’s point of view, API-first design encourages defining functionality early and allowing form to follow from it. The presence of API output as raw data means that devs can focus on business logic over interface considerations. This also forces a concentration on the core of an app and the value it will provide, and might help put extra bells and whistles into perspective (“Do we really need that?”).

Fast iteration and efficiency

This method also allows fast iteration on new features. Suppose a Widget model has been changed, and now has many Parts instead of one. If the model is critical to the app, a change like this might cause other sweeping changes across an app’s interface. In many situations, the solution is for a developer to quickly mock up a quick-and-dirty interface that’s just good enough for testing. Once the appropriate features have been accepted, a designer might start nearly from scratch to re-implement forms and other elements in a more aesthetically pleasing way. This is inefficient, and can create a dependency because the designer waits for the back-end portion to be finished before starting their work. API responses can be mocked (once a spec is agreed on), meaning development and design teams can work at the same time, with neither stepping on the other’s toes.

Central documentation

Finally, an API built this way helps to centrally document an application. An API contains all of the central business logic that a developer starting out needs to know, reducing the bus number of the project. It also doesn’t contain cruft that’s (mostly) irrelevant to back-end design, e.g., does making a purchase on the site take multiple page-steps? This kind of information should be packaged in the web app, away from the data manipulation of an API. Some caveats:

• Story acceptance with APIs might be difficult for non-technical project managers. Indeed, the ideal of being able to separate back-end and UI features given above might be impossible on some projects.
• Using an API separately can introduce overhead, e.g. separate API servers will most likely need to be maintained from the start.