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.
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.
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.
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.
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.
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
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.