When kicking off a new API integration project, we often star
by getting the technical specifications on the external API. The specifications
should often come in the form of an OpenAPI Specification or a JSON schema
definition. It is often the case, that the external API may not be available
for the implementation effort to start. This however should not block our
development effort because we can create API mocks without much development effort.
The mocks can echo back our original request with the same JSON document model
or with some modifications.
We are going to work on a simple telemetry digest API and
see how we can create a mock. But before, we look at the solution, let’s review
some important concepts. This should help us have more background on what we
are trying to achieve and understand the tooling that we are using.
What is OpenAPI Specifications
The OpenAPI Specifications (OAS) is a technical standard for
defining RESTful API in a declarative document, which allows us to clearly
understand the contract definitions, and the operations that are available on
that service. The OpenAPI Specification was formerly known as the Swagger Specifications,
but it has been adapted as a technical standard, and it was renamed.
The specification is often written using YAML, which is a
human-readable text file that is heavily used on infrastructure configuration
and deployments. In our case, we will be using this following YAML, to
understand a simple service.
👍 Use Swagger.io to create an OpenAPI specificastion doument like the one above.
What is Postman and the Echo APIs
Postman is a development tool that enables developers to
test APIs without having to do any implementation work. This is a great
approach as it enables the development team to test the API and clearly
understand the technical specifications around security and contract
definitions.
Postman provides several services. There is a client
application that should be used to create a portfolio of API requests. There is
also an ECHO API service that enables team to create mocks by sending the
request to that service, which, in turn, echoes back the request with
additional information.
When an external API is not available, we can use the ECHO
API to send our HTTP operations to quickly create realistic mocks for our
implementation effort as this integrates with external services, and we can
make changes to the JSON response to mock our technical specifications.
👍 Note: Use https://postman-echo.com/post
for the Echo API
What is Azure API Management
The Azure API Management service is a reverse proxy gateway
that manages the integration of APIs by providing the routing services,
security and other infrastructure and governance resources. It provides the management of cross-cutting
concerns like security policies, routing, document (XML, JSON) transformation,
logging in addition to other features.
For our purpose, we can use the YAML specification that was
previously defined to create a new API definition, as this is supported by Azure
APIM. By importing this document, a new API is provisioned with the default
domain (or custom domain for production environments) on the service plus the
API routing suffix and version, which defines the RESTful route on the URL. An
example of this would be:
api-ozkary.azure-api.net/telemetry/v1/mock
In the lifecycle of every request, APIM enable us to inspect the incoming request, forward the request to a backend or external service and inspect or transforms the outbound response back to the client application. The inbound and outbound process are the steps in the API request lifecycle that we can leverage to create our API mocks.
Look at a Simple API Use Case
We can now move forward to talk about our particular use
case. By looking at the YAML document, we can see that our API is for a simple
telemetry digest that we should send to an external API.
Each telemetry record should be treated as a new record;
therefore, the operation should be an HTTP POST. As the external service
processed the request, the same document should be returned to the client
application with the HTTP status code of 201, which means that the record was
created.
For our case, the Postman Echo API adds additional data
elements to our document. Those elements are not needed for our real
implementation, so we will need to apply a document transformation on the
outbound steps of the request lifecycle to return a document that meets our
technical specifications.
As you can see on the image below, the response from the
Postman echo service returns our request data in the data property, but it also
adds other information which may not be relevant to our project.
Create a Mock to Echo the Requests
Once the YAML is imported into Azure APIM, we can edit the
API policies from the portal. To mock our simple telemetry digest, we need to
add policies to both the inbound and outbound processing steps. The inbound
step is used to change the inbound request parameters, headers and even the
document format. In this case, we need
to change the backend service using the set-backend-service policy and
send the request to the postman-echo.com API. We also need to rewrite
the URI using the rewrite-uri policy and remove the API URL prefix.
Otherwise, that will be appended automatically to our request to the Echo API,
which will cause a 404 not found HTTP error.
When the response comes back from the Echo API, we need to
transform the document in the outbound processing step. In this case, we need
to serialize the body of the response, read the data property, which holds the
original request, and return only that part of the document. For this simple
implementation, we are using a C# script to do that. We could also use a liquid
template to do something similar. Liquid templates provide a declarative way to
transform the JSON response. It is a recommended approach when we need to rename
properties and shape the document differently, which in some cases can get very
complex. When using the C# code approach the code can get very hard to
maintain.
👍 Note: The C# capabilities on Azure API are very limited. When applicable, the use of liquid templates is recommended.
Conclusion
With every new integration project, there is often the need
to mock the APIs, so the implementation effort can get going. There is no need
to create some API mock project that requires a light implementation and some
deployment activities. Instead, we can use Azure API Management and Postman
echo APIs to orchestrate our API mocks. By taking this approach, we accelerate
and unblock our development efforts using enterprise quality tooling.
Thanks for reading.
