Programming
Maintaining tests for API's can become a heavy task depending on how many API's and routes you have to maintain and how often things are added.
One could also think of offshoring the testing to a dedicated company. I gave it a try and received offers which calculated a fee for each route to test.
Unfortunately, none of the companies I contacted bothered going into details what kind of tests they will deliver.
I use the API first or design first principle to outline the requirements of the API under development and do this by defining it with OpenApi specifications.
I wrote an article some time back of the tools I use to write OpenApi definitions.
Introduction
Througout this post I am describing the path it took me to specify my own REST API's (API specifications) as well as how to document them in a browasable and accessable way.
It focues on tools to simplify your work but also includes topics like mocking and linting.
A summary in git project can be found at the bottom
If you are developing REST API's for internal or external use, you will need to document it at some point. To do so, probably the best approach is to follow a given standard. Some of the goals we can achieve with this, is:
- fast starting point for new developers
- follow the same principles
- standardize and follow best practices
- save time (compared to writing your own specs)
- use tools (document, try out, test, mock, stub)
Postman is without doubt a handy tool when it comes to API testing. Often I get new API's which I need to test out before implementing them. Most of those API's are JSON or XML and Soap based. First thing is allways throwing the examples at postman and try out the APIs test endpoint.
Most of JSON API's use a bearer token to authenticate, you one just has to set the Authorization header which shouldn't need explaining.
Some SOAP API are still using username and password within a Security envelope, which are part of the body.
All those scenarios are very easy to test in postman. However, Postman has its own feature just for authentication. Because postman is essentially browser based (looks like an electron app to me), I thought it would be nice to have the same user grant flow as I recently tested.
In this previous post, I was implementing the authorization code flow with proof key for code exchange with a local standalone keycloak server on my nuxt single page app.
I am not going over the setup again, as I already described it, I am just going to share the steps involved to use the exact same configuration to authenticate postman on the same keycloak server, even using the same client.
Postman authenticate with 'authorization code flow and pkce'
Create or edit a collection
In the collection, choose the Authorization tab and configure the settings as seen in the screenshot.
The same setting are available for single requests, but doing so in the collection lets us inherit the authentication to its requests.
Provide your credentials
If the configuration provided is correct, you are prompted for your credentials in a new window. Fill in the form, postman will catch the redirection on success and return with the authorization token. Additionally, the refresh token is provided as well.
Be aware, postman will not automatically regenerate the authorization token with the refresh token, but you can renew it within postman as long as the refresh token is not expired.
Technically, postman could grap your credentials, so I advise to use this only with test credials on localhost.
Keycloak is keeping a short default expiration time, which is good on production, but maybe anoying testing in postman on localhost. You can easily increase the default timeout of 5min (300s) in your keycloak settings.