Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Publishing API Console on Bitbucket Pages

DZone's Guide to

Publishing API Console on Bitbucket Pages

In this article, we provide some guidelines that will help you to configure the CI process to build and publish an API-Console.

Free Resource

The State of API Integration 2018: Get Cloud Elements’ report for the most comprehensive breakdown of the API integration industry’s past, present, and future.

My partner Caio Oliveira and I have been working together in our free time to build an API project related to the travel sector.

We've used RAML to define it and it's amazing because RAML allows us to build a simple and very well documented API. The definition is exposed using API-Console which builds RAML definitions to a friendly and beautiful web component.

We're using Bitbucket to host our source code; not only the definition but the implementation as well. This is a private project but we decided to publish the API definition into a public space.

Since API-Console generates an HTML component, we decided to publish it using Bitbucket Pages, which, similar to GitHub Pages, is an incredible way to publish static content and make it public to the internet.

Following the instructions provided by Bitbucket, we've created a new repository to host the API-Console and this is our structure:

  • api-travel: repository used to host our API definition and implementation.
  • bitbucket.travelanalytics.io: repository used to host our bitbucket pages.

We've started to publish our content manually using the api-console-cli (a command line tool used to build the console) and pushing this to our Bitbucket page repository. Since this process takes a long time and was inspired by this guide, we decided to move forward and use Bitbucket Pipelines to automate this "build" and create a simple and very consistent CI process to our API-Console.

This guide will help you to configure the CI process to build and publish an API-Console.

Create a New Bitbucket User

This is not an obligation, but having different users will help you to organize your process and will make sure that the specific users have the right permissions to access your repositories.

Follow the instructions to create a new user in Bitbucket and associate that user with the repositories with the right permissions. In our case, we've created a specific user and associated that account with the following permissions:

  • Permission to read into api-travel repository.
  • Permission to read/write into the bitbucket.travelanalytics.io repository.

Create an SSH Key for the User

We will need to create an SSH key and use it to authenticate access to our repositories during the pipeline flow to clone and push data.

Create an SSH key using the following command:

ssh-keygen -t rsa -N '' -f ~/.ssh/my_ssh_key

*This command will create a new ssh key pair into your .ssh folder with the name my_ssh_key

In Bitbucket, go to your "Bitbucket settings" and insert the content of the my_ssh_key.pub into the "SSH keys":

Image title

Please refer to these instructions for more information about creating SSH keys.

Configuring Pipelines

In the repository where the pipeline will run, go to "Pipeline-->Settings" and enable it.

api-travel repository:

Image title

Now let's set up the private key generated in the previous step as a variable of the pipeline. We'll use this key to grant access to our repositories during the flow.

Pipelines do not support line breaks in environment variables so we need to base64 it:

Linux: base64 -w 0 < private_key

Mac: base64 < private_key

Go back to "Pipelines-->Environment variables" and create a new variable with the name "SSH_KEY." Copy the result of the previous command to the "Variable value" and check the box "Secured."

Image title

Create the Pipeline Script

In our repository, we're creating a pipeline script (bitbucket-pipelines.yml) with the base instructions and another script (build.sh) with the proper commands to build the console, commit, etc.

Also, we'll use a cache strategy for our npm dependencies. The cache will help us to save some time avoiding pipelines that consume unnecessary time downloading dependencies.

Please refer to the following links for more information about pipelines and caching.

In the Source view, create two files with the following content and commit them to the repository.

bitbucket-pipelines.yml - This is our pipeline configuration:

# This is a sample build configuration for JavaScript.
# Check our guides at https://confluence.atlassian.com/x/14UWN for more examples.
# Only use spaces to indent your .yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:8.11.1

pipelines:
  custom:
    deploy-api-console:      
      - step:
          name: Build
          caches:
          - node
          script:
            # Install api console cli
            - npm install api-console-cli
            # Call build.sh script
            - chmod +x build.sh && ./build.sh

build.sh - Script to be executed by the pipeline:

#!/bin/bash
set -e # Exit with nonzero exit code if anything fails

# Configure SSH KEY
echo $SSH_KEY > ~/.ssh/id_rsa.tmp
base64 -d ~/.ssh/id_rsa.tmp > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa

# Save some useful information
TARGET_BRANCH="master"
REPO="git@bitbucket.org:travelanalyticsbr/travelanalyticsbr.bitbucket.io.git"
SHA=`git rev-parse --verify HEAD`

# Clone the repo a foler. We'll use api/ as a working dir.
git clone $REPO api-console-build

# We don't need old build anymore...
rm -rf api-console-build/**/* || exit 0

# Build the console out of the latest API release.
echo "Building the console..."
node ./node_modules/api-console-cli/bin/api-console-cli.js build src/main/api/api.raml

# Copy console
cp -a build/. api-console-build/

cd api-console-build

# Setup a person who will made the commit
git config user.name "TravelAnalytics CI"
git config user.email "travelanalytics.ci@travelanalytic.com.br"

# Stage files
git add -A .

# Verify changes in git
if git diff --staged --quiet; then
    echo "No changes to the output on this push; exiting."
    exit 0
fi

echo "Deploying..."
# Commit the changes
git commit -m "Generated new version of the API console: ${SHA}"

# Push to git
git push $REPO $TARGET_BRANCH

Running the Pipeline

In this scenario, we've configured the pipeline to execute manually using the tag "custom." If you want to execute automatically after a commit you should use "default."

Please refer to this link for more information about the pipeline configuration.

To execute the pipeline go to the "Branches" view, click on the action menu and select "Run pipeline for a branch."

Image title

Please refer to this link for other options to run pipelines manually.

A console log will open showing the execution process.

Image title

If the pipeline runs successfully, your API-Console will be published on Bitbucket Pages!

Image title

Your API is not enough. Learn why (and how) leading SaaS providers are turning their products into platforms with API integration in the ebook, Build Platforms, Not Products from Cloud Elements.

Topics:
raml ,bitbucket ,bitbucket pipelines ,integration ,api integration

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}