API First: From Zero to Hero (Part 2)

3Bit Technologies
4 min readFeb 29, 2020

In this second part of the API First: From Zero to Hero (Part 1) article, we will level up by provisioning an API Gateway, import the API and run our API tests against the gateway.

Importing an API into API Gateway

Moving on with the integration tests, we will import our API into the API Gateway locally, to validate the import process and enable the use of our test through the gateway. We will have something similar to the diagram below:

Provisioning the API gateway

To facilitate the provisioning of resources, we will start to use a Makefile to centralize the scripts and enable the reuse of them.

Below is the initial structure of our Makefile to provision the API Gateway (Kong):

From now on, we can already run our Makefile to check if the provisioning will be successful:

make -k run-integration-tests

If everything happened successfully, the output of the command should have looked like the image below:

Basically what we’ve done in this Makefile so far:

  • We created a shared network that will be used by Kong and its database (Postgres), the backend of our API (prism) and the client of our API (newman)
  • Provisioned the postgres database used by Kong
  • We provisioned Kong using database
  • We cleaned-up by removing the created containers and the network, this is because we want them to live only during the test execution

Provisioning the API backend (prism)

Now we will use the same command (with some minor changes) that we used to create the Prism Mock and add it to our Makefile, to automatically provision the mock API backend.

First, we will remove the container from the prism that we had previously provisioned:

docker rm --force prism

With that, we changed our Makefile:

We can run our Makefile again:

make -k run-integration-tests

The output of the command must be the error-free execution of the suite.

Importing the API

We will now import our API definition inside the Kong API Gateway.

For this, we will increase our Makefile with additional commands to run the tool swagger-to-kong, developed by us specifically for this purpose.

Adding the registry as insecure (Optional — self-generated certificates)

Before using the tool, we will have to configure docker’s registry as an insecure in the docker daemon, to avoid problems due to self-generated certificates.

To do this, change the /etc/docker/daemon.json file with the changes below:

"insecure-registries" : [ "registry.domain.com" ]

To take effect, restart the docker daemon:

systemctl restart docker

Pulling the swagger-to-kong image:latest

To ensure that we have the last image available for the swagger-to-kong component, pull the image as shown below:

docker pull registry.domain.com/ci-tools/swagger-to-kong:latest

With the registry configured, we can use the swagger-to-kong tool properly.

Below is the Makefile with the necessary changes:

Configuring the swagger-to-kong component performs the following actions:

  • Import the openapi petstore-v3.0.yaml definition
  • Changes the address of the item servers in openapi with the value of the environment variable OPENAPI_SERVER, which in turn points to the backend (Mock). This setting is applied in Service Kong.
  • Invokes the kong Admin API to create the appropriate Service and Route.

Executing the collection via Makefile

With everything working properly, we can now invoke our collection with Newman using our Makefile.

We will use the same command used previously, with minor adjustments to the container network to share the same network as Kong.

Follows the Makefile with the changes:

If we try to run the Makefile now, we will have an error because the environment localhost.postman_environment.json used by the collection petstore-collection.json has been configured with the Variable baseUrl pointed at the computer local (localhost) and now we need it to be configured to point to Kong (API Gateway) on the network known to him in Docker.

To change the environment, we must go back to Postman and follow the same steps that we already did in the section Creating an environment and exporting, changing the value of Variable baseUrl to http://kong:8000.

The result should be the same as below:

Don’t forget to export the environment with the same name as the previous one!

We can then run our Makefile, now with integrated tests using newman!

make -k run-integration-tests

API First: From Zero to Hero (Part 3)

Want to know more? Don’t forget to visit us at https://www.3bit.com.br/3bit



3Bit Technologies

Cloud Specialists providing professional services with DevOps, BigData, Cloud Native Applications and Security. https://www.3bit.com.br/3bit