API First: From Zero to Hero (Part 1)

To develop and manage microservices APIs following the best practices and open standards, ensuring quality and security, we created this hands-on article demonstrating how we can use opensource tools and common techniques to make it possible to enable an ‘API First’ approach.


  • Kong as the API Gateway


Follow the requirements to run the examples demonstrated in this tutorial:

  • Docker installed

We will use the petstore-v3.0.yaml spec as our OpenApi contract.

Important: Note that we used Linux to run all commands, but it’s completely possible to run on Windows using tools like gitbash or wsl.


After the installation, open the Postman console so we can start designing our API:

Importing the OpenApi spec on Postman

It’s possible to import an OpenApi spec directly on Postman:

  1. On Postman console, click on Import

3. Choose the file petstore-v3.0.yaml

4. On the next screen click on Next to finish the import process

API Mocking with Prism

The best way to start explore our API using Postman and then write integration tests is to mock our API so we can easily simulate calls without a real backend implementation.

For that, we need to run a Docker container with Prism pointing to our OpenApi spec:

cd tutorial-apifirst 
docker run --rm --name prism -d -p 4010:4010 -v :/etc/openapi/spec.file stoplight/prism:3 mock -h docker logs prism

If you succeeded to run the container, you should see an output similar to this one:

[CLI] ... awaiting Starting Prism...
[HTTP SERVER] ℹ info Server listening at
[CLI] ● note GET
[CLI] ● note POST
[CLI] ● note GET{petId}
[CLI] ▶ start Prism is listening on

For this point is possible to invoke the tool curl to check if our API Mock is working:

curl http://localhost:4010/pets/1

The output should be:


Exploring our API through Postman

With everything set up, we can explore our API using Postman.

Changing the API target URL to our Mock

We need to change the URL from our API on Postman to the local address of our Mock:

  1. On the navigation bar, right click on the collection Swagger Petstore and than click on Edit

First exploratory test

  1. On the navigation sidebar, choose one of the available requests under the collection Swagger Petstore on the folder pets, like List all pets for example.

First API Test

From the output generated by our Mock, we can create our first test to check if the returned output is what we really were expecting.

Prism returns always the same value for each Json data type, making it easy to preview and test this values.

Tip: It’s possible to keep this same values for the Mocks generated for the microservices backend tests (Spring Boot for example), so the same API tests (created in Postman) can be reused to make integration tests with the real microservices API implementation.

Steps to create our first real test:

  1. On the request screen click on the tab Tests
pm.test('expect response be 200', function () {

pm.test('expect response json valid', function () {

3. Click on Send to make the request and execute the tests

4. Check the test results by clicking on the tab Test Results right under the test text field, on the response section.

5. Click on Save (near to the Send button) to save the changes

On this test scenario, we validated the following conditions:

  1. Assert that the HTTP Status Code should be equal to ok (HTTP 200)

Exporting the collection

At this point we have:

  • The API Mock running

We can now export this Postman collection so we can execute it via command line, giving us the hability to add this tests in a CI/CD Pipeline:

  1. On the navigation sidebar, right click on the collection Swagger Petstore and then click on Export

Creating and exporting a Postman Environment

On postman, we have the concept of Environments, that are an abstraction to store configurations used by the collection during the execution and may change depending on the target environment.

We will create an Environment so we can export it together with the Collection, changing the variable baseUrl that we used in our collection targeting our Mock:

  1. On postman’s workspace, on the right corner click on the icon Manage environments (gear tool icon)

Executing the collection via command line

In order to run the collection petstore-collection.json and execute our tests, we'll use a tool named Newman (command line runner for Postman):

If the command succeeded, the result output should be the following:

We have our API (spec openapi) designed, validated and with automated tests!

API First: From Zero to Hero (Part 2)

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

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