An Overview of APIs and API Management

With the advent of internet communication technologies and tools, every device is now capable of communicating with another device. Communication is possible because all the devices speak in one language or have translating tools or functions that help them talk to each other. Every programmer in today’s world works with APIs either as a developer of the API or as the consumer of the API.

What Is an API?

API stands for application programming interface. API can be any one of the following:

• A web service endpoint.
• A web API endpoint.
• A function signature in a program.

An API is anything that acts an interface to the outside world or external program. It’s a common misconception that the API is something that a functionality endpoint shared on the internet. It can be any contract in a library file, an interface in your application, or some functionality exposed by a vendor that is exposed to another program to consume.

In this article, we will learn more about APIs and little about API management in the context of internet programming interfaces. So, what are the basic points to take care of while exposing endpoints to the outside world?

• A service that is exposed through the internet should be reliable.
• It should be secured and well-documented.
• You need a gateway that acts as a proxy and manages the number of requests by creating SLAs and other policies.
• An API should be available for subscribers to subscribe to the service and each subscriber should be validated by the service.
• You need a dashboard that displays the analytics and statistics of the requests made.
• You should provide high availability of your services.

How can we manage the above features? The answer is using the API management tools provided by different vendors. These tools can be either available on-prem or in the cloud. API management provides a flexible way for you to expose your APIs to developers.

What API Management Tools Are Available?

There are many API management vendors available, including:

• Apigee.
• IBM API management.
• Microsoft’s AZURE API management.
• MuleSoft’s Anypoint platform for APIs.

Can I Share API Information With Other Developers?

The answer is yes. Most tools support open API specifications like RAML, Swagger, WADL (Web Application Description Language), and WSDL (Web Services Description Language). AZURE API management supports all the above-specified formats except RAML. RAML is supported by MuleSoft and is also a widely accepted specification for creating APIs by many vendors.

RAML will be discussed more in this article. The open specification language is a specification that can be provided to developers before the actual services implementation and to the outside world once the services are deployed for consumption.

RAML stands for RESTful API modeling language and it is used to describe RESTful APIs. Right now, two versions of RAML are in use: 0.8 and 1.0. Most tools support 0.8 and only a few support 1.0.

Note: RESTful APIs have become synonymous to the term APIs because they use the capabilities of the existing HTTP supported methods like GET, PUT, POST, DELETE, and are lightweight. With the support of JSON, the request and response aren't needed to transform, as they can easily be understood by all the JavaScript frameworks.

For creating RAML files, MuleSoft provides an IDE. There is a package provided by MuleSoft called API Workbench that can be added as an extension to a free software tool called Atom. This extension has very good set of functionalities for creating resource types, traits, types, and other components for designing a RAML file.

RAML 1.0 is more mature, but when you develop the specifications, make sure that it will be supported by the API management tool that you are using. API Notebook, provided by MuleSoft’s Anypoint Platform, also does not support RAML 1.0. I was getting a weird error while playing with it and so had to change the version to RAML 0.8.

What Are Examples of APIs?

Most of the APIs that have been used in different apps are:

• Google Maps.
• Weather Channel.
• Twitter API.
• Facebook API.
• Pinterest.
• Instagram.
• Tumblr.

For example, Google Maps API can be used to embed Google Map into the web pages and it can be used by mobile applications along with the desktop applications. Similarly, there are other APIs provided by NASA and other government institutions. If you count the APIs available, the list is ever expanding as you see a new API published by one or other company in the world.

One simple API that I could think of is an Account API with the operations as below:

• Add account.
• Get accounts.
• Get a particular account by account ID.
  • Delete the account.
  • Update the account.
  • Get the account details.

The above operations can be roughly translated as below:

• Your service URL: https://dummybank.com/accountsservice.

• Get Accounts: https://dummybank.com/accountsservice/api/accounts — HTTP GET OPERATION.

• Create Account: https://dummybank.com/accountsservice/api/accounts with a request body — HTTP POST OPERATION.

• Get Account by Account ID: https://dummybank.com/accountsservice/api/accounts/{id} — HTTP GET OPERATION.

• Delete Account by ID: https://dummybank.com/accountsservice/api/accounts/{id} — HTTP DELETE OPERATION.

• Update Account by ID: https://dummybank.com/accountsservice/api/accounts/{id} with a request body — HTTP PUT.

What Is the Purpose of API Management?

• Helps in packaging and deployment of the APIs.
• Publishes the APIs to developers and other consumers.
• Provides documentation and sample requests/responses for developers to understand the APIs.
• Provides an API console that you can use to test the API operations. (Most of API management tools provide mock endpoints that we can test before testing the actual endpoints.)
• It acts a proxy or façade for existing backend services.
• To provide reliability of the service and analytics dashboard.

Microsoft’s AZURE API management and MuleSoft’s Anypoint Platform for API have two common features:

1. API Gateway service.
2. Developer portal.

Publisher Portal is a different feature or a page available in the AZURE API management, whereas in Anypoint Platform, the Administrator will publish a portal using API Administration, which is like Publisher Portal. You can define SLAs, throttling and other policies for an API.

We can generically come up with the following diagram for API management:

Figure 1: API management.

In Figure 1, if we observe there are three categories of consumers: developers, applications or consumers, and administrators or publishers.

Developers

Developers referred to in the above diagram are any outside developers who register for API access and play with the APIs through Developer Portal. They are the interested parties who like to explore the APIs and can become a future consumer with appropriate licenses.

Applications and Consumers

Applications in the above figure referred to mobile applications, desktop, and tablet applications that consume the APIs to perform a certain function. Imagine a most common scenario where we go to Walmart and buy a TV. When we scan our credit card, it might send a request to Visa or Master Card or any other card services and validates our information and based on the response from the actual service, the transaction will be approved. Similarly, for all the online transactions that we make, we will be using the APIs to perform the operations.

Publishers and Administrators

Publishers and administrators are the ones who publish the APIs to the outside world. They can be an inside developer who has developed the APIs or a specifically designated person who takes the APIs information and helps in publishing them or a combination of the two.

In the diagram, we also observe that there are three components in the middle of consumers and actual services: Developer Portal, Gateway/Proxy, and Publisher Portal.

A portal is a set of web pages and is designed to cater to specific functionality.

Publisher Portal

Publishers or Administrators publish the APIs, documents related to the APIs, and other sources needed to consume the APIs through Publisher Portal. Also, Publisher Portal is the place where the API-specific security configurations, accesses, and other restrictions defined and controlled.

Also, the limitations on the APIs are provided by defining tiers such as a free tier where outside developers can register and play with the APIs with some limitations like five requests in a minute and 100 requests per day. There's also a premium tier in which the application can make 500 requests per minute and one million per day, as well as an unlimited tier where the application can make unlimited calls. These are all defined in the Publisher Portal by linking the APIs with the different tiers defined.

Also, limitations can be placed on the access by linking the APIs access to a group and imposing approvals on the subscriptions or access provided to the emailed users.

Developer Portal

Once the Publisher publishes the APIs, they will be accessible to the outside developers through Developer Portal. Developer Portal provides access to the APIs and the operations supported and the instructions to consume the APIs like request and response samples and the details regarding throttling. Some vendors provide APIs registration-free and some need to be registered before using. Also, at the time of registration, each subscriber will be provided a subscriber key and password or a set of primary and secondary key and password pair or a client ID and a password. The terminology basically varies from vendor to vendor but the concept remains the same.

Gateway/Proxy

Applications either consume the actual service directly or through a gateway or a proxy layer based on how the services are deployed. Some vendors implicitly provision gateway services before the actual service as a layer and hide the actual service. For example, Microsoft API management implicitly provides Gateway endpoint and hides the actual services. All the consuming applications consume the services through Gateway endpoint. Anypoint Platform provides the option to deploy Gateway endpoint; otherwise, the actual endpoint is accessed directly by the Developer Portal. Anypoint Platform provides the option to deploy the services or gateways through CloudHub. CloudHub is an integration platform as a service (iPaaS). Gateway applications hide or proxy the backend services and protect the actual endpoints from the consuming applications.