Automating API Blueprint publishing to Apiary with Bitbucket Pipelines

As the number of connected devices rapidly increases, system-to-system communication is starting to dominate human-to-system interactions. Systems don’t need appealing interfaces or dazzling animations, they need well-defined and documented contracts — APIs. API-first approach presents a tremendous opportunity for teams who are willing to adapt — design and document APIs before the applications that will consume them even exist.

Continuous publishing

Continuous integration and delivery are two well-known software engineering practices that help to keep up with constant change. Those practices can also be easily applied when designing API specification.

Several tools that allow to verify if your API looks, feels, and functions the way you want, are already available. When using API Blueprint to document your API, Apiary is the best choice when it comes to prototyping, validating, mocking or sharing your API specification.

Apiary supports syncing with GitHub repositories out-of-the-box but it’s also easy to set-up if you’re using some other Git repository hosting.

Most of my repositories are stored on Bitbucket, so normally I would use a third-party service like Travis CI or Codeship. But lately I received a beta access to Atlassian’s new CI service called Bitbucket Pipelines and I decided to give it a shot.

Let’s go to the fun stuff.

Assumptions

  1. You created a new Bitbucket repository and cloned it to your local machine,
  2. You added some files (e.g. package.json) to your repository and pushed to the remote,
  3. You created a new Apiary project,
  4. You have Node.js, Ruby and Bundler installed on your machine,
  5. You have beta access to Bitbucket Pipelines (DM or tweet Joshua Tjhin for one).

Enabling Bitbucket Pipelines

  1. Navigate to the settings screen of your Bitbucket repository,
  2. Click the “Pipelines → Settings” button,
  3. Click the “Enable pipelines” switch,
  4. Click the “Create bitbucket-pipelines.yml” button.
Enable Bitbucket Pipelines

Setting up Apiary API Token

  1. Navigate to the Apiary API Tokens page,
  2. Click the “Generate New Token” button,
  3. Copy the generated API Token (it’s alphanumeric, e.g. 44112a2f61bf2c71c37908d3b1f7638d),
  4. Navigate to the settings screen of your Bitbucket repository,
  5. Click the “Pipelines → Environment variables” button,
  6. Type APIARY_API_KEY in the first text field,
  7. Paste the API token in the second text field,
  8. Check the “Secured” checkbox,
  9. Click the “Add” button.
Add APIARY_API_KEY environment variable

Setting up the project

First, pull changes from you remote repository. This will download the bitbucket-pipelines.yml file that was created after enabling Pipelines for your repository. Your directory should now contain two files:

bitbucket-pipelines.yml
package.json

Now add required dependencies.

Add Apiary CLI gem to your Gemfile,

source 'https://rubygems.org'
gem 'apiaryio'

install bundle,

bundle install

and add both, Gemfile and Gemfile.lock files to your repository.

Next, add api-blueprint-validator-module and yargs NPM packages:

npm install api-blueprint-validator-module yargs --save

The api-blueprint-validator-module module doesn’t have its own executable script, so you have to create a simple wrapper. Create validate.js file in the root of your repository with the following content:

validate.js file

Next, you have to add two scripts to your package.json file. One for schema validation (testing) and one for deployment (publishing). Replace YOUR_PROJECT with the name of your Apiary project.

{
...
"scripts": {
"test": "node validate.js --files api.apib",
"publish": "apiary publish --api-name=\"YOUR_PROJECT\" --path=\"api.apib\""
},
...
}

Finally, you have to add API specification file to your repository. For the purpose of this tutorial you can use one of the official API Blueprint examples. Download one of the exemplary blueprints to the root of your repository and rename it to api.apib.

Commit all new and changed files. Your project should now look like:

api.apib
Gemfile
Gemfile.lock
package.json
bitbucket-pipelines.yml
validate.js

Configuring Bitbucket Pipelines

Bitbucket Pipelines reads build configuration from single bitbucket-pipelines.yml file stored in your repository. The content of this file is structured around keywords that shape the anatomy of your build configuration. You can read more at the official Pipelines documentation.

Bitbucket Pipelines runs builds with Docker so the official ruby image can be used (it’s much quicker to install Node.js using nvm than installing Ruby in Node.js container).

“Automated publishing” build process should install required dependancies, validate schema of the blueprint file and then publish specification to Apiary project. To achieve this, update your bitbucket-pipelines.yml file with the following content:

bitbucket-pipelines.yml file

Commit updated configuration and push changes to the remote repository. Pipelines should now run the build and deploy API blueprint to the Apiary project.

Summary

Each push to remote repository should now trigger a new build. You can check the build history in the Pipelines” screen of your Bitbucket repository.

When clicked, each log item shows detailed build log for every script command.

Bitbucket Pipelines also displays a small indicator of build status for each commit on the “Commits” screen.

Every successful build now publishes your API Blueprint specification to Apiary project.

Found issues or errors with the process outlined above? Let me know! Do you know a quicker or easier method? Let me know!

Build awesome things…

Thanks for reading! Please get in touch with me on Twitter if you run into any issues. And, please share this with others that you think would find it useful.

Update August 8, 2016

I’ve open sourced my API Blueprint boilerplate project: https://github.com/jsynowiec/api-blueprint-boilerplate, so you can skip most of above steps and just add the configuration for CI server of your choice.