Modern Web applications use the
microservice architecture for their API service integration. These APIs are
often a combination of internal and external systems. When the system is
internal, there is better control of the API endpoints and contract payload
which the front-end components consume. When there are external systems, there is no
real control as the endpoints and contracts can change with new version updates.
There are also cases when the
integration to these external integrations must be done with multiple providers
to have some redundancy. Having to integrate with multiple providers, forces
the application to manage different endpoints and contracts that have different
structure. For these cases, how does the client application know what API
endpoint to call? How does it manage the different structure and formats, JSON or
XML, on both the request and response contracts? What is the approach when a
new external service is introduced? Those are concerning questions that an API
Gateway can help manage.
What is an API Gateway?
An API Gateway is an enterprise
cloud solution that integrates client applications to back-end services or
APIs. It works as a reverse proxy which forwards inbound requests to internal
or external services. This approach abstracts the service's endpoint details
from the application; therefore, an application only needs to be aware of the
gateway endpoint information.
When dealing with disparate
services, an application must deal with the different contracts and formats,
JSON, XML, for the request and subsequent response. Having code on the
application to manage those contracts, leads to unmanageable and complex transformation
code. A gateway provides transformation policies that enables the client
application to only send and receive one contract format for each operation.
The gateway transformation pipeline processes the request and maps it to the
contract schema required by the service. The same takes place with the response,
as the payload is also transformed into the schema expected by the client
application. This isolates all the transformation process in the gateway and
removes that concern from the client.
API Settings
To better understand how an API
Gateway can help our apps avoid a direct connection to the services, we should
learn about how those services and their operations should be configured. To help us illustrate this, let’s think of an
integration with two disparate providers, as shown on the image below.
The client apps can be using the
APIs from either Provider A or B. Both providers are externally located in a
different domain, so to manage the endpoint information, the apps are only
aware of the gateway base URL. This
means that independently of how many providers we may add to this topology, the
clients always connect to the same endpoint.
But wait, this still leaves us with an open question. How is the routing
to a specific provider handled?
Operation Routing
Once we have the base URL for
the gateway endpoint, we need to specify the routing to the API and specific
operation. To set that, we first need to add an API definition to the gateway.
The API definition enables us to add an API suffix to the base URL. This suffix
is part of the endpoint route information and precedes the operation route information.
An API definition is not
complete unless we add the operations or web actions which handle the request/response.
An operation defines the resource name, HTTP method and route information that
the client application uses to call the API endpoint in the gateway. Each route
maps to an operation pipeline which forward requests to the provider’s API
endpoint and then sends the response back to the client. In our example, the routing for the operation
of Provider A looks as follows:
This image shows us how an API
has a prefix as well as operations. Each of the operations is a route entry
which completes the operation URL path. This information, plus the base URL,
put together handles the routing of a client request to a particular operation pipeline,
which runs a series of steps to transform the documents and forward the request
to the provider’s operation.
Note: By naming the operations
the same within each API, only the API suffix should change. From the
application standpoint, this is a configuration update via a push update or a
function proxy configuration update.
Operation Pipeline
The operation pipeline is a
meta-data driven workflow. It is responsible for managing the mapping of the
routing information and execution of the transformation policies for both the
request and response. The pipeline has four main steps: Frontend, Inbound,
Backend and Outbound.
The Frontend steps handles the Open
API specifications JSON document. It defines the hostname, HTTP schemes, and security
requirements for the API. It also defines, for each operation, the API route,
HTTP method, request parameters or model schema for both the request and
response. The models are the JSON contracts that the client application sends
and receives.
The Inbound step runs the transformation
policies. This includes adding header information, rewrites the URL to change
the operation route into the route for the external API. It also handles the transformation
of the operation request model into the JSON or XML document for the external
API. As an example, this is the step that transform a JSON payload into SOAP by
adding the SOAPAction header and SOAP envelope into the request.
The Backend step defines the base
URL for the target HTTP endpoint. Each operation route is appended to the
backend base URL to send the request to the provider. On this step, security
credentials or certificated can be added.
Lastly, the Outbound step, like
the Inbound step, handles header and document transformation before the response is sent back to the client application. It transforms the JSON or XML payload
into the JSON model defined by the Frontend schema configuration. This also the
place to add error handling document standards for the application to handle
and log accordingly independently of the provider.
This is an example of a
transformation policy which shows an inbound request transformed to SOAP and
outbound response transformed to JSON.
Conclusion
In Microservice architecture, a
client application can be introduced to disparate APIs which support multiple
document structure and different endpoints, as these API services are hosted in
different domains. To avoid complex code which deal with multiple document
formats and endpoints, an API Gateway can be used instead. This enables us to
use meta-data driven pipelines to manage that complexity away from the app.
This should enable the development teams to focus on app design and functional
programming instead of writing code to manage infrastructure concerns.
Have you faced this challenge
before, and if so, what did you do to resolve it? If you use code in your app,
what did you learn from that experience?
.png "ozkary api orchestration")
.png)
