Mock recording allows an API Fortress user to pass API requests and responses directly into the API Fortress mocking platform. This largely eliminates the need to manually create mock response cases. To do so, we're making use of the Kong Microgateway.
The process is divided into a few parts. Here's how we're going to approach it:
- First, we're going to turn on the Kong proxy server.
- Next, we're going to create a proxied endpoint.
- Finally, we're going to push that proxied endpoint into API Fortress mocking.
A few of these steps are fairly technical, but we're going to be as explicit as possible with the documentation and as always, if you need assistance, feel free to reach out to email@example.com.
Let's make sure we have everything we need:
- An updated version of the API Fortress
core/docker-compose.ymlwhich includes the Kong section at the end. The bottom of your docker-compose should look like this:
The initialization script,
The start script,
If we have all of the above, perfect! We're ready to start. If not, feel free to reach out to firstname.lastname@example.org to let us know what you need!
First, we need to ensure that at the API Fortress Postgres instance is running. Execute the following command from the command line and ensure that it is running:
The image below is the entry that you're looking for:
Next, we need to initialize Kong. This is done by running the previously mentioned script,
Issue the following command from the command line:
Once Kong has finished initializing, we can proceed.
Next, we need to start the Kong container itself. We do so by issuing the following command:
Once the container has finished starting, we can do a
To view the currently running containers and verify that we started it successfully.
Finally, we can verify that the proxy is up and running by issuing the following cURL command from the command line, or an identically structured HTTP request from the HTTP client of your choice (note: replace the 'apif.example.com' component with the corresponding part of your instances URL):
A positive response from this route indicates that the proxy server is up and running. Congratulations! You now have a live proxy server!
Our last step in the setup phase is creating an API Fortress API key. The gif below shows the process.
- Click the gear in the upper right corner of the view
- Click "API Keys" in the navigation bar on the left
- Click "+API Key"
- Name and save your API Key. It's helpful at this point to copy the key and secret to an easy to reach location, as we'll need it in later steps.
Alright! The proxy is up. Let's learn how to proxy a route.
First, an important note!
It is ideal for every subdomain mentioned herein to have a DNS entry pointed at the server running API Fortress. Our suggestion is, wherever possible, to introduce a wildcard entry. That is to say, if API Fortress is running at 'apif.example.com', the wildcard entry of '*.apif.example.com' would point at the same IP address and allow every prepended domain to reach the same server.
In order to proxy an API route, we need to send the following request to the proxy via HTTP (again, this can be done via cURL or your HTTP client of choice):
name: the name of the API profile
upstream_url: the origin URL (the destination that we're passing through the proxy on our way to)
hosts: A list of hosts that will trigger this API profile (the URL(s) that will trigger this proxied response)
So, we're sending a post to
apif.example.com:8001/apis with headers defining a
hosts. The result is a profile of a proxied API.
nameof the profile is
hostfor the profile is
Naturally, when you do this yourself, you'll be replacing
"apif.example.com" with the URL of your API Fortress instance.
The last step in the setup phase would be to test the actual proxied route itself. To do so, execute the following command in the command line or send it with the HTTP client of your choice:
Here, the 'header:value' string would be replaced with any required header key/value pairs that you need to submit. The URL would be replaced with the URL previously defined as the host, appended with port 8000, and then followed by any necessary routing. Our expected response should match the response of the endpoint that we're proxying, provided we're passing the correct headers.
As with creating the actual proxied endpoints, creating recorded mocks requires a modification of the DNS. Adding a wildcard entry for the mock server (
*.demoapi-mocks.apif.example.com) will allow these requests to be properly routed once the mocks are recorded.
The next step is to activate the
fotress-http-log plugin for Kong. In order to do so, we must format and send the following request, either through cURL or the HTTP client of your choice:
Another big HTTP request! Let's unpack the components therein.
Initially, we're passing a number of url-encoded key/value pairs in the POST body (commonly known as post parameters). These values are largely static.
config.api_key: The API Key value created in step 1.
config.secret: The API Secret value created in step 1.
config.mock_domain: The mock domain you wish these routes to be appended to in API Fortress Mocking. It does not need to already exist.
The URL we're actually sending the request to:
needs to have the first part of the URL (
apif.example.com) replaced with the URL of your self-hosted/on-premises API Fortress instance.
Once this request has successfully been sent, the fortress-http-log plugin for Kong will be active, and mock recording will be enabled!
Record a mock by calling the proxied API. Issue the following call from the command line or from the HTTP client of your choosing:
In this case, we'd be recording the
/api/retail/product route of our proxied API to the mock domain we configured in the first call (
demoapi-mocks.apif.example.com). As always, note that the proxy route in this call must be replaced with the proxy route that you created. Also, note that the port in this case is
8000 rather than
Finally, we can verify the new mock route in two primary ways. First, we should now see it in the Mocking interface in API Fortress. Second, we can query the route directly via cURL or the HTTP client of your choosing:
We should receive the same expected response to this call that we receive when polling either the actual or the proxied API. Note that in this case, the previously required header is no longer explicitly required, and that it's been replaced with a header that requests the mock endpoint specifically.