Continuous Integration with Apiary, Dredd, and Wercker

There are many tools in the market to design, develop, and test API's. Some of these tools could be used separately. Some others could be combined. Every time a change is introduced in the design or implementation of an API, it would be nice to have tests and builds run automatically. Continuous Integration (CI) is a software development practice that allows builds and tests to be triggered every time new code is pushed to the repository. There are may tools that could be used to build this CI pipeline. This blog will share the experience of building a CI pipeline using Apiary (bought by Oracle in January 2017) for API Design and Wercker (bought by Oracle in April 2017) to help achieve this CI goal.

1. 1. Create an API definition in Apiary

Apiary (apiary.io) improves API development by promoting a documentation first approach. It is a platform for designing HTTP based web APIs. It starts with API documentation, then Apiary creates mock services and tests. Apiary support two formats for API description: API Blueprint and Swagger.

In Apiary, from the API dropdown select “Create New API Project” and the “New API” screen will popup.

Find below an example of an API Blueprint description as displayed in the Apiary Editor.

• The FORMAT keyword shows this API description document is API Blueprint.
• The name following the first level heading “#” is the API name.
• The “hola” resource follows the second level sub-heading “##”. The “/hola” URI is inside of the square brackets.
• The “hola” action follows the third level sub-heading “###”.  The “GET” HTTP method is inside of the square brackets. It returns a 200 status code and a JSON.

1. 2. Create an API Implementation Repository in GitHub

Many developers use GitHub to store their API implementation code. It is good practice to store the API documentation with the code. Apiary allows you to sync up with GitHub and therefore complete the Continuous Integration process: from definition, to implementation, to build and test. Apiary Pro further allows to create branches and use workflows like GitHub Flow.

In GitHub’s welcome screen, select “New Repository” to create a repository. Then add your API implementation source code files. In this example, a Node.js implementation is being used with start script app.js.

1. 3. Sync Up Apiary API to GitHub Repository

In the Apiary Editor, select the “Link this Project to GitHub” option. This will take you to the API Settings page. In the section to sync your API description with its implementation, select the “Link this Project to GitHub” option again. Finally search and connect to the repository that contains your API implementation.

Your Apiary API settings will show the synced API description file and the Apiary Editor will show the GitHub Branch and the “Push” button to propagate your API definition changes to the code repository.

1. 4. Test the API implementation with Dredd

Apiary's open source project Dredd is a tool that can be used to validate an API description against its implementation. It checks the API implementation responses with the ones described in the API description document.

Since a Node.js API implementation is being used in this blog (as mentioned in Step 2), add dredd to the dependencies in the package.json file. Also add the test script to run dredd tool.

Note that according to the above package.json file, the dredd.yml file is to be placed in the ‘api-blueprint’ folder of the GitHub repository. Add a dredd.yml file in this folder. If you happen to have a local install of dredd, you could run ‘dredd init’ to generate this dredd.yml file.

1. 5. Use Wercker for Continuous Integration for this API

Wercker helps achieve continuous integration and continuous delivery (CI/CD) with micro-services and Docker. Wercker uses a wercker.yml file to define the configuration of the pipelines via a set of steps. Since we are using a Node.js based API implementation, npm install and npm test are to be added to the Wercker pipeline (npm is the is the default package manager for the JavaScript runtime environment Node.js).

In the below example a “build” pipeline is specified with two steps: (1) npm install and (2) npm test. Whenever a project is created in Wercker, a “build” pipeline is automatically created with a GitHub hook that executes this “build” pipeline. The Wercker step ‘npm-install’ executes the ‘npm install’ command with the optional leveraging of the Wercker cache mechanism to improve installation time ‘npm-install use-cache’. The Wercker step ‘npm-test’ executes the ‘npm test’ command that runs a package’s “test” script. For example, add this wercker.yml file to the root of the GitHub repository.

Add an Application on http://app.wercker.com

The application is now listed on the Wercker Pipelines

1. 6. Test the CI Pipeline from a change in Apiary’s API definition document

Goto to Apiary and add a change in the API definition document and Push to the GitHub repository.

This triggers a build in Wercker.

Inspect the build and see that every step completed successfully.

Open the ‘npm-test’ step and check that all dredd tests passed.

The highlighted link above provides a URL to check the Dredd test results in Apiary. You may choose to save this test results for the ‘helloworld’ API and it will be saved on Apiary > Tests > Continuous Integration.

Additional scenario where Wercker pipeline detects missing API implementation

Let's test now when a new API is defined and and its implementation is not present yet. When endpoint /ohayo is added in Apiary and these changes are pushed to the Github repository, it will trigger a build in Wercker. This build pipeline fails as shown below in the npm-test step as the implementation for /ohayo has not been added yet.

When the /ohayo implementation is added in Github and the changes are committed, it will trigger an automatic build and test in Wercker. This time, it will succeed as the implementation provides the output specified in the API definition.

These simple 6 steps complete the integration circle. Starting from API definition in Apiary, to storing the code implementation for this API in GitHub and synchronizing this repository with Apiary. Following by API automated testing via Dredd and building a CI Pipeline in Wercker. Finally testing the pipeline and storing the Continuous Integration test results back in Apiary.