Technical Documentation

Generic API Translation

By 03/06/2019 June 17th, 2019 No Comments
Aptira Generic API Translation

One of the key aspects of designing modern applications is to have an interface defined as Application Programming Interfaces (API) that allows businesses to securely expose content or services to both their end users and the customers.

Consider an enterprise application that needs to support different set of clients that may belong to varying domains. Each of these clients would have a set of interface requirements using which it would interact with the enterprise application. For example: An online retail store that runs varied sets of applications to sell products might need to support clients such as Mobile native application, Desktop/mobile browsers. Clients can also be API developers who develop innovative applications using the capabilities that an application expose.

Hence it is important to design an architecture that decouples the interface from the functionality, focusing more on the execution of actual business logic rather than integration mechanism. With many designers structuring their applications into a set of loosely coupled, collaborating services with each exposing an API, an API management mechanism is required that would mediate and integrate different set of clients with these services.

Another driving factor to have a mediation layer is to support the integration of applications with the legacy systems that either support proprietary interfaces or interfaces which are not yet planned to be modified due to cost associated with it. For instance : A system that fetches the data from traditional Network Management system and passes it to its API based back-end systems, needs to support an SNMP adaptation layer.

An API management layer acts as an API gateway that hides all the underlying implementation details and exposes consistent interfaces to its consumers. Following are some of the factors to be considered while designing applications using API gateway.

NOTE: In all the examples discussed below, assumption is that the applications deliver their services using the REST API.

Interface Protocol

Depending on the type of the application or the system, what is the underlying protocol over which the services are delivered to its consumers. Is it the standard HTTP/HTTPS/SOAP/LDAP or a proprietary protocol that consumers support. API gateway needs to have a protocol adaptation layer that converts consumer specific protocol to the backend API mechanisms. For example: If the consumer supports only SOAP then any request sent over this protocol should be parsed and translated to REST by the API Gateway.

Data Mapping – Representation

Most of the current applications are designed to transmit JSON payload. But legacy systems still support old data format such as ASN or XML. So, API gateway should parse this data by taking into considerations the serialization and deserialization of data, data representation i.e. ASCII or UTF-8 and translate it to JSON payload to be sent in REST API. Since any data loss would impact the backend processing, care must be taken to map the parameters from incoming data format to JSON format by retaining the data representation.

Data Mapping – Structure

After the representational and format differences are catered to in the Data Mapping – Representation function, the mapping requirements that must next be handled relate to the actual data model. Data elements are logically converted to the appropriate base type (i.e. integer, real, text, date, timestamp etc) so that they can be manipulated. The Data mapping that occurs here can be simple re-ordering or restructuring (e.g. creating new record structures), or can involve more complex functions, such as calculated items or unit conversions (e.g. imperial to metric conversions). This data mapping can be defined as simple declarative configurations, such as a field-to-field conversion map or may require more complex processing that involves procedural logic and decision processing.

Data Mapping – Semantic

Mapping the data model will satisfy most use cases but there often is a larger objective: to ensure that the underlying meaning of the data is transferred between API caller and recipient in a usable way. Although the techniques for performing semantic mapping can be similar to logical data model mapping, the problems of semantic mapping are often more subtle and wide-reaching.

For example an auto scaling policy is applied on a system when a KPI reaches a specific threshold. Each system is designed in a different way and has a different way of calculating the KPIs. Instead of projecting each system’s KPI(such as CPU load, Memory) it is easier if it can be normalized across multiple systems by creating a mapping between the common KPIs to the system specific KPI. Such a mechanism to semantically data across different systems can be designed using API gateway.

Semantic mapping uses the same underlying data manipulation capabilities as the Logical Data model mapping, but typically requires a more intensive calculation model, possibly including persisting data values between API transactions, performing lookups and more complex algorithms.

Semantic mapping is also the API mapping function that could potentially use ML/AI capabilities.

Security control

The application developers design the applications around the security framework using which they are able to provide secure services. One of the components of this framework is the User management which can span across multiple domains. Hence it is important to control access to application APIs by restricting them from direct access to sensitive data. Such access control would require security policies for authentication to be defined such as Single Sign On, API keys, OAuth 2.0, Data Masking and any other custom defined policies. Such policies are easier to manage by defining them as part of Security framework layer in the API gateway.

Traffic Control

Each of the back-end systems of the application are designed to support a specific API traffic pattern. Traffic patterns are outside the control of the application since it is dependent on the behaviour of the client applications. Any change in the API traffic pattern for the systems would impact its planned resource usage and the performance of the whole application. Since the API traffic can be from any of the client applications, it is important to control the API traffic for the whole application and also the back-end systems that deliver the services. API gateway should have a mechanism to set a threshold for the API traffic and should have appropriate error handling mechanisms to indicate such conditions to the client applications.

API Monetization

Some of the applications are designed to support end-users that are either enterprise customers or the developers who use this for their research purposes. For instance: OpenWeatherMap is a website that publishes detailed weather conditions based on the location co-ordinates by exposing an API. It is important to distinguish these sets of end-users since API traffic requirements for each one of them is different. To ensure services delivered with better Quality of Service (QoS) based on the end-user, it is important to measure the usage by having an appropriate billing mechanism. Hence an API gateway should have an API monetization platform that can bill the end-users based on the API usage.


In nutshell, with most of the current applications designed around microservices based architecture and API first principle, it’s quite evident that an API gateway that acts as a single-entry point, plays an important role for the Enterprise customers in delivering secure services to a wide spectrum of their user base.

Let us make your job easier.
Find out how Aptira's managed services can work for you.

Find Out Here

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.