The Value of Specification First Development Using Swagger

The explosion of public facing APIs such as those provided by Twitter and the New York Times have changed the way programmers make software. Today, it is not atypical for a programmer to create applications that are essentially an aggregation of data and services provided by a variety of public APIs. Yet, as the need for APIs grows, so does the need for workflows that streamline the development process to make them. The days of making it up as you go along are coming to a close. The days of Specification First Development are coming, and for many shops they’re here already. Specification First means that all work emanates from an ever evolving, but controlled specification. This includes coding, documenting, and enhancing software. Although some fear that Specification First will remove speed, creativity, and innovation from the practice of making software that counts, I am here to tell you differently. Specification First makes it possible to easily and accurately publish inventive APIs that are easy to consume and easy to maintain. Specification First does not hinder development; it empowers development.

Allow me to elaborate, but before I do, let me share something with you. I used to be of the camp that believed that specifying software slowed things down. I took to heart the part in the Agile Manifesto that says, working software over comprehensive documentation.

In the old days of making software, a high ranking engineer or business analyst wrote the specifications and then we coded to that spec. It was laborious effort that involved hand written specification followed by hand written code. Over time, the tools for making specifications evolved so that some code generation took place. But you could still drive a truck in the space between writing specification and having working code. When it comes down to spending money, back then, I would take the code every time. But that was then and this is now. What changed my thinking? Swagger.


You can view the Swagger specification project for the application on SwaggerHub.

Everything Emanates from the Spec

At the enterprise level, just having a tool that allows developers to easily create API code and documentation based on a common specification is not enough. You need to have a workflow process to make sure everyone is rowing in the same direction. Otherwise, you are in Development Hell.

Development Hell is a place where a developer adds an endpoint, or changes an API endpoint request/response definition and doesn’t inform those responsible for publishing documentation that the API has changed. Then, one day those depending on the API to get work done wake up to a bunch of broken code and have no idea about how to fix the problem because the endpoints defined in the API do not match the documentation. At best, the company publishing the API is the subject of flame and ridicule on the Internet. At worst, customers flee.

Specification First addresses the need to keep code and documentation in sync always. As mentioned above, the premise of Specification First is that all code and documentation emanates from a common Swagger 2.0 compliant API specification expressed as either YAML or JSON. Thus, when it comes time to update an API, the first place anyone goes is to the specification. (Please see Figure 2.)

Figure 2: The workflow for Specification First is simple and easy to adopt.

Change is made in the spec and then the code is regenerated along with the accompanying documentation. (Please see Figure 3.)

Figure 3: A tool such as SwaggerHub allows you to create interactive API documentation that is derived from the same Swagger specification you’ll use to create your base code.

Now you may ask, when I regenerate, won’t the existing code base be wiped out? The answer is, not if you are careful. The code generated under a tool such as SwaggerHub is the base code only. No implementation logic is generated. Implementation logic is the work of developers. Thus, when you go about Specification First, you need to make sure that the application code is structured in such as way that the operational entry point that is bound to a given endpoint is separate from implementation logic. The way you do this separation will vary according to the language/framework you use. SwaggerHub supports code generation in NodeJS, Spring-MVC (Java), Sinatra (Ruby), Asp.Net 5, and Silex (PHP), to name a few. When you design an application architecture that has a strong separation between API endpoint entry code and implementation logic, you’ll be able to maintain the integrity of your code after any regeneration event with minimal tweaking.

Putting it All Together

As I mentioned at the beginning of this piece, the number of applications that depend on public APIs accessed over HTTP is growing every day. Programming using an API based on REST is a way of life. Thus, the way people program is changing, too. Today, there are a number of software shops that do not write any UI code. Their bread and butter is publishing APIs.

More applications will be consuming more APIs more often. And, as the appetite for an API grows, the need to make modifications to those APIs quickly and communicate those changes accurately to the user base becomes paramount. It’s no longer just about getting the bits out there. You need to get the bits and docs out there at the same time. Specification First is a practice that, if followed vigilantly, will allow you to ensure the synchronous publication of code and documentation. Having API code and documentation emanate synchronously from a single, common specification makes delivering APIs continuously not only possible, but easy. Specification First will not slow you down. It will speed you up, maybe faster than you ever imagined.

More by Author

Must Read