Writing a Documentation-First API

October 21, 2014 Appirio

By Neil Hastings


While building our new micro-service based architecture for our Topcoder platform, we’ve learned how important it is to specify interfaces clearly and concisely. A key part of the architecture is for each of the micro-services to expose RESTful APIs. And developing APIs goes well beyond just “coding”. The scope of all that is required to develop APIs properly goes beyond the scope of this blog post, but the key part I will focus on is the need to design, define, and document your APIs in a consistent manner.

I attended the I Love APIs conference hosted by Apigee a few weeks ago where I took in a session on Swagger, which a specification for describing RESTful APIs. According to the Swagger Specification site here is the goal of the specification: “The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”

Fortunately, this is just what we needed for the Topcoder build. We are big believers in using web standards where possible, so we love the idea of having standards-based way of documenting our API.

The conference also had a session on the a127 project, that integrates the Swagger API specification with NodeJS. The demonstration showed off a number of features such automatic client bindings and server-side stub code generation, automatic routing and validation of API requests as well as out of the box support for OAuth 2.0, Caching, and Quota Management. Needless to say we were hooked.

We have started utilizing the a127 toolset and developed a process for getting our API developed using our Topcoder platform. The basic process is as follows:

  1. Create or update the yaml file.
  2. Launch a Topcoder challenge to create or update the NodeJS API code
  3. Integrate challenge results

Let’s step through each of these.

The Yaml File

In the heart of our project is a yaml file, which complies with the Swagger 2.0 specification. Using this standard yaml file has allowed the team to standardize our communication to each other and the community. One team member will create the yaml then others will comment and iterate on the file until we are ready to pass the file off to the community. Here is an example yaml file that was used to create the initial code for a Challenge service.

Once the yaml file has been settled upon, we insert the file into our base NodeJS API server. The base NodeJS API server is a quick start tool for creating an API server from a YAML file. It contains configuration management, PostgreSQL database bootstrapping and schema migration along with response helper tools. We just insert the file at api/swagger/swagger.yaml and start the server. This gives us a full documentation server based upon the UI and is ready to add NodeJS controllers and models.

Create the Controllers and Models

Once we have a validated swagger yaml file inserted into our NodeJS base API, we can launch a Topcoder challenge to create the NodeJS controllers and models. This is the easy part. Either launch an assembly or code challenge, write a short description of what you are looking for, and either point to the git repo containing the base NodeJS API code or attach it to the challenge. We have had great success in both assembly and code challenges.

Integrate and Iterate

Now we have a fully functional and fully documented API. The beauty of this process is that our API documentation will always be up to date. If the swagger yaml file is not in sync with the NodeJS controller then the API will not work and tests will fail.

Now iterate. Make small changes to the swagger file and launch another challenge to update the NodeJS controllers. Here is an example of an iteration challenge.

It’s still early, but this process has worked well for us so far and utilizing Swagger and a127 toolset has allowed us to focus more on the actual design of APIs rather than all the underlying mechanics.

Closing thoughts

I hope you find the process useful for creating documentation first APIs. I’d like to thank Apigee and Wordnik for creating such useful tools. Also, please look for challenges implementing swagger based API’s on Topcoder.com.

Previous Article
Sending Emails without a targetObject ID in Apex
Sending Emails without a targetObject ID in Apex

Next Article
Moving Data from Amazon S3 to Salesforce Wave
Moving Data from Amazon S3 to Salesforce Wave

Many of us use Amazon S3 every day, and we don’t even know it. If you have ever looked at a picture on Pint...