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.
Tools
- Kong as the API Gateway
- Keycloak as the IAM solution
- Postman for the creation of the integration tests
- Newman for the execution of the integration tests
Requirements
Follow the requirements to run the examples demonstrated in this tutorial:
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.
Postman
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:
- On Postman console, click on Import
- On the popup, tab Import File click on Choose files
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 0.0.0.0 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 http://0.0.0.0:4010
[CLI] ● note GET http://0.0.0.0:4010/pets
[CLI] ● note POST http://0.0.0.0:4010/pets
[CLI] ● note GET http://0.0.0.0:4010/pets/{petId}
[CLI] ▶ start Prism is listening on http://0.0.0.0:4010
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:
{"id":-9223372036854776000,"name":"string","tag":"string"}
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:
- On the navigation bar, right click on the collection Swagger Petstore and than click on Edit
- On the popup, click on tab Variables
- Replace the current value of the variable baseUrl with the address: http://localhost:4010
- Click in Update to confirm the changes
First exploratory test
- 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.
- Change the parameter limit to 1
- Click on Send to execute the request
- Check the result on the tab Body
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:
- On the request screen click on the tab Tests
- Paste the content below on the text field.
pm.test('expect response be 200', function () {
pm.response.to.be.ok
});
pm.test('expect response json valid', function () {
pm.expect(pm.response.json()).to.be.an('array').that.have.length(1)
pm.expect(pm.response.json()[0]).to.include({'id':-9223372036854776000,'name':'string','tag':'string'})
})
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:
- Assert that the
HTTP Status Code
should be equal to ok (HTTP 200) - Assert that our return is a valid JSON document
- Assert that the returned json is an array
- Assert that the number of itens on the array is 1
- Assert that the object on the position 0 of the array should be:
{'id':-9223372036854776000,'name':'string','tag':'string'}
Exporting the collection
At this point we have:
- The API Mock running
- The API imported on Postman and configured to target our Mock
- Some API tests executed against our Mock
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:
- On the navigation sidebar, right click on the collection Swagger Petstore and then click on Export
- Keep the default options
- Click on Export to confirm
- Save the collection under the same folder of this tutorial, with the name
petstore-collection.json
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:
- On postman’s workspace, on the right corner click on the icon
Manage environments
(gear tool icon) - On the popup Manage environments, click on Add to add a new environment
- On the popup Add Environment, type the environment’s name, on this tutorial we will use localhost
- Add the variable baseUrl with value http://localhost:4010 for the INITIAL VALUE field
- Click on Add to confirm the configuration
- On the popup Manage environments, click on the option Download Environment over the just created environment localhost
- Save the collection under the same folder, with the name localhost.postman_environment.json
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