Use Jenkins To Keep Your API Gateway Definitions Automatically Updated

February 13, 2019 · by Duncan McAllister ·

An API is only useful if gets in front of its intended audience, and that includes both the initial launch of the API and—perhaps more importantly—its many subsequent improvement iterations. Deployment velocity becomes critical to the success of your API as you iterate; simply put, you’ve got to get the improved version in front of the audience as quickly as possible.

Akamai API Gateway includes a robust set of administrative APIs that enable automation of many aspects of API delivery. Using these APIs—along with a bit of Jenkins, as you will see below—you can construct a continuous integration (CI) process that will ensure any changes made to your API definition are automatically synced with your Akamai API Gateway configuration. This automated process, in turn, increases your deployment velocity for the improved API.

How it works

API developers commonly maintain resource descriptions for their APIs using API definition languages such as Swagger or RAML. In a nutshell, these resource descriptions are blueprints that characterize the capabilities, semantics, and usage of APIs in a standardized way. Akamai API Gateway was designed to leverage these common descriptive frameworks.

Using either Swagger or RAML specifications, here’s what an adaptive CI process might look like for an API developer using API Gateway:

Pipeline flow diagram

In the above visualization, an API developer makes a change to an API definition (as denoted by the state of the Swagger or RAML file) and then develops API code to support the described definition. Once complete, the developer commits and pushes changes to the version control system. When the changes reach the version control system, this will trigger a webhook to start the automated CI process shown above. In other words, the API Gateway CI pipeline for the API reacts and adapts automatically when a change to the codebase is detected.

To accomplish this adaptive pipeline, we need to interact with a few key Akamai API Gateway resources.

Pipeline process

The above process shows the API Gateway CI pipeline’s logical activities (blue boxes) and the related API Gateway resources (green boxes) that support the pipeline. This is how the process works (the numbered steps below are enumerated in the illustration above) with high-level descriptions of how Akamai API resources are used to interact with the API Gateway product:

  1. An API developer makes changes to an API specification, commits the changes to a repository, then pushes changes (i.e., a “push event”) to a specific branch for their API project in the version control system.
  2. The push event to the version control system causes a webhook to trigger the pipeline clone process (“Clone VCS Project” in the diagram above).
  3. The pipeline clones the master branch to its workspace.
  4. The pipeline compares the API resources defined in the Swagger or RAML file to the Akamai API definition. Then it modifies the specified API version using the API definition resource.
    1. NOTE: This step is accomplished by retrieving a JSON representation of the API Gateway configuration state using the ‘Get a Version’ API resource:resource1 Both the API EndPoint ID and version number are passed in the URL of the API resource request to retrieve the version details of the API Gateway instance described using JSON format. Using this JSON representation, both the API resource definition configuration (for resource comparison between the Swagger/RAML specification) and the activation state can be determined. This information will be referenced in the following step.
  5. The pipeline identifies the latest activation state (from the API definition retrieved in the previous step) and checks the activation status of that version on both production and staging networks.
    1. 5a: If that version is not active on any network, the pipeline proceeds to update the API Gateway definition using the provided Swagger or RAML specification.

      1. NOTE: Updating the API Gateway resources using a Swagger or RAML file is performed using the ‘Create an endpoint from an API definition file’ resource. Specifically, a multipart/form-data request is sent by preparing a form data POST request body using the definition file and setting the appropriate payload fields such as the importFileFormat (swagger or raml), and Content-Type header (in our case, application/x-yaml):resource2
    2. 5b: If that version is active on staging or production, the pipeline creates a new version of the API definition.
      1. NOTE: The creation of a new API Gateway definition version is performed using the ‘Clone a Version’ resource. Both the API EndPoint ID and version number (used as the source of the clone operation) need to be referenced in the API resource URL:resrouce3After a new version is created, the API Gateway resources are updated using the Swagger or RAML specification described in step 5a above.
  6. The pipeline then activates the new version on the staging network.
    1. NOTE: Activation is accomplished using the ‘Activate a Version’ resource. A JSON request body is prepared which indicates the activation network (staging or production), a list of email recipients to receive notifications on activation status, and activation notes:resrouce4

      This JSON request payload is included in the POST body along with the API EndPoint ID and Version Number in the API resource URL:


  7. The pipeline then automatically orchestrates a process to test the API resources through the Akamai Staging network, providing timely feedback to the developer of any problems.

This workflow provides the following benefits:

  • The process of promoting changes to API specifications is fully automated, which enables API developers to focus on improving their codebase instead of manually managing infrastructure. This type of reactive CI pipeline eliminates the overhead of constantly reconciling API specifications.
  • The API specification (Swagger or RAML) remains the single source of truth for all API resources.

An example CI process

Let’s take a look at a more specific example so you can see how this might work when implemented. The first step is to modify the Swagger or RAML API specification. In this example, an API developer modifies the endpoint resource '/test' to be '/test-demo' within their local software development branch. From there, the developer commits the change to a GitHub project via a push event to the remote master branch. This GitHub project also has a webhook configuration enabled to trigger the pipeline immediately after the developer push event to the remote branch.

VCS webhook diagram

The push action triggers a Github webhook which initiates a Jenkins job that is the first in a series of related deployment tasks (see the deployment pipeline visualized in the screenshot below). This first job clones the Github project containing the Swagger or RAML API definition into the local Jenkins workspace. From there, Jenkins orchestrates the process of automatically cloning the API Gateway definition (creating a new version), updating the new definition version using the Swagger or RAML file resource, and then activates it on the Akamai Staging network.

Jenkins pipeline screenshot

So that’s how you automatically reconcile changes to an API spec with Akamai API Gateway and Jenkins. You can find more tips and tricks for API Gateway here

You can find the code referenced here on GitHub.

Duncan McAllister is a senior enterprise architect at Akamai Technologies.