API World
With the advent of internet communication technologies and tools, every device is now capable of communicating with another device. Communication was possible because all the devices speak in one language or have translating tools or functions that helps them to talk to each other. Every programmer we contact in today’s world, most of them say that they are working 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 shares on the internet. It can be any contract in a library file, or 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 delve more into APIs and little into 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 internet should be reliable.
- It should be secured.
- Needs to be well documented.
- 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.
- Need a dashboard that displays the analytics and statistics of the requests made.
- Should provide high availability of your services.
How can we manage the above said 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 flexible way to expose your APIs to the developers.
What are the API Management tools available?
There are many API Management vendors available and these are the few of the vendors that I am aware of
- Apigee
- IBM API Management
- Microsoft’s AZURE API Management
- MuleSoft’s Anypoint Platform for APIs
Can I share the API information with other developers?
The answer is YES. Most of the 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 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 of the tools are supporting 0.8 and only few support 1.0.
Note
RESTful APIs have become synonymous for the term APIs because it uses the capabilities of the existing HTTP supported methods like GET, PUT, POST, DELETE and it is lightweight. With the support of JSON, now the request and response is not needed to transform as it can easily be understood by all the JavaScript frameworks.
For creating RAML files, MuleSoft provides IDE for creating the RAML and there is a package provided by MuleSoft called “API Workbench” which can be added asextension to a free software tool called “Atom”. This extension has a 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 they will be supported by the API Management tool that you are using. “API Notebook” provided by MuleSoft’s Anypoint Platform also does not seem to 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 the 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 maps 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.
A 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.
- Publishing the APIs to developers and other consumers.
- Provides documentation, sample request/response for developers to understand the APIs.
- Provides API Console that you can use to test the API operations. (Most of the API Management tools provides 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 has two common features,
- API Gateway service
- Developer portal
“Publisher Portal” is a different feature or a page available in the AZURE API Management whereas in Anypoint Platform Administrator will publish a portal using “API Administration” which is like “Publisher Portal” where 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 general
In figure 1, if we observe there are 3 categories of consumers i.e. Developers, Applications and Administrators or Publishers.
Publishers/Administrators
Publishers/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 specific designated person who takes the APIs information and helps in publishing them or a combination of the two.
Developers
Developers referred to in the above diagram are any outside developers who register for the API's access and play with the APIs through Developer Portal. They are the interested parties who like to explore the APIs and can become future consumers with appropriate licenses.
Applications/Consumers
Applications in the above referred to mobile applications, desktop and tablet applications consume the APIs to perform certain functions. Imagine a 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 validate 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 in fact we will be using the APIs to perform the operations.
Then in the diagram, we observe that there are 3 components in the middle of consumers and actual services i.e. 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 will be publishing 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, access and other restrictions are defined and controlled.
Also, the limitations on the APIs are provided by defining tiers like a Free Tier where outside developers can register and play with the APIs with some limitations like 5 requests in a minute and 100 requests per day and a Premium Tier where the application can make 500 requests per minute and 1 million per day and 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, those 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/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 service before the actual service as a layer and hides the actual service. For example, Microsoft API Management implicitly provides a Gateway endpoint and hides the actual services. All the consuming applications consume the services through Gateway endpoint. Anypoint Platform provides the option to deploy the Gateway endpoint otherwise, the actual endpoint is accessed directly by the Developer Portal. Anypoint Platform provides 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 protects the actual endpoints from the consuming applications.
Backend services are the actual services that sit behind the proxy if present, otherwise they are directly consumed by the consuming applications.