Explaining API Management To A Layman

I was thinking today of one scenario; i.e., if I had to teach API Management to a layman, how would I teach it? I tried to convince myself that it would be very easy to do but at the first instance of thinking about it, I got blocked. Then, I thought for a while and came up with this. Anyone who is reading this article is requested to put their knowledge aside and see if my article makes sense. Good luck with that!

So, here is my imaginary story to teach API Management.

John works for a company called “checkphotos.com” and he has developed a software that takes a photo of a person’s face as input, compares it with the faces in the existing photo database, and returns an indicator as an output that tells if it has matched or not. He gave a demo to his team and everyone likes it.

Figure 1 – Face Feature comparison

His company has installed security cameras around their office and captured the photos of people who come around and tested their software as if it could identify the new faces captured in the photos and it was a huge success.

Then, their company’s CEO wanted to enhance the software by integrating with their alerting system so that any new face should provide an alert to the security team. John successfully integrated his application with their alerting system and it started working fine by providing alerts whenever there is no match found. Everyone appreciated John’s work.

Figure 2 - Integration with Alerting system

John documented the operations, sample input/output data, and the application flow for other developers to integrate his application with theirs. John, then, named the document as “Face Recognition Software API”, where API means Application Programming Interface. Application Programming Interface is any program contract that helps other programs to consume the API application.

This news spread to other branches of his company and they also wanted to implement the recognition software in their offices and they wanted to reuse the application that John developed. So, John had to convert his application to be a service exposed on internet.

Figure 3 – API converted to a Service that can be exposed through internet

All the other branches successfully started consuming the recognition service developed by John and could use their centralized database to verify the face features. This has become a great implementation and news spread to other companies too.

Figure 4 – Service exposed to other offices through internet

At the beginning, everything went well but slowly, the requests increased and the service was not able to cope up with the requests. So, John had to create two instances of the service and add a software that balances the requests to the service. It was called Load Balancer.

Figure 5 – Added a load balancer

The news spread to other companies and some two companies were interested in using the service developed by John. John’s CEO thought it would be benefiting to their company if they provide their software as a service (SaaS) and deploy it on Cloud.

John deployed the service to a cloud as Cloud Service and the two companies “signofface.com” and “verifyfaces.com” started consuming the service. It went well for a month. But, John had to setup a WebEx meeting with those two companies to explain them what he has done and went through the technical documents that developed. Whenever they had questions, he had to answer their questions.

Figure 6 – Moved the service to cloud

John started thinking how could he simplify the consumption of his service so that the developers who consume his service could do it by themselves - something like a “Self Service Portal” where the portal should have all the details required for consumption and the developers should be able to test his service with the supported operations without his involvement.

After a month, John faced these issues,

Requests tripled after a month and then it started multiplying by 10 times every day. This cost more to the company.
His company could not control the requests and they did not have any mechanism to control the number of requests.
Also, one hacking group attacked their service with DDOS attack by sending millions of requests per second. Their service went down for few days.
Since the service was consumed directly, whenever John had to change his service, his customers had to change their code.

John met the cloud architect Sam and presented him with the issues that he was facing and then, Sam proposed a solution for his issues. He mentioned that the cloud website has a feature called “API Management” and it should help him to solve his issues.

John logged into his cloud website and created an API Management Service from the “API Management” feature and found that there are two different Portals available under the service: DEVELOPER and PUBLISHER.

He could access both as he was the administrator. He opened the PUBLISHER portal and created different consumer groups: FREE, PREMIUM, and UNLIMITED. He configured FREE group with a setting that number of requests allowed for a minute is 50 calls and 500 calls per week. He configured PREMIUM group with a setting that number of requests allowed for a minute is 1000 calls and 5 million per week. For UNLIMITED, he allowed unlimited calls.

He created Visibility groups for each consumer group: ADMINISTRATORS, DEVELOPERS, CONSUMERS. ADMINISTRATORS group consisted of his company administrators; and others who would like to test the service and functionality were added to the DEVELOPERS group.

Each subscriber to the service needed to get approval from the administrator and he mapped DEVELOPERS with the FREE group so that they could test but with limitations. Based on the consumer’s subscriptions, they have been assigned with the consumer group. Each subscriber is provided with a subscriber ID and subscriber Password and they should send these while making the call.

This has provided control over the usage of the service. Also, instead of sharing his service load balancer endpoint, he gave the new endpoint that was generated by the API Management Service. The new endpoint acted as a proxy to his service and all the requests to the actual service must pass through the proxy service first. This has removed the dependencies between his service and the consumers. No one knew the actual load balancer endpoint anymore and so the service endpoint became more secured.

He has added the operations supported by his service and the sample requests/responses; and provided a mock endpoint that acts on behalf of his service for testing.

Figure 7 – Configured service using API Management Solution

Developers who subscribed to the service now got access to the DEVELOPER portal. Now, developers could read the documentation and could test the operations supported, by using testing console, that was using mock service and mimicking the actual environment. The developers found it to be very useful and they could also find a source for a code for consuming the service in different programming languages. Developers could integrate their applications and tested the functionality. John didn't have to give demos or explain his service to the developers any more. This facilitated John being able to fulfill his goal of providing a Self Service Portal.

Also, he could view many analytics reports showing the number of requests coming from each customer, failed and successful requests and the load per day, year and other graphs that could give him more insight into the requests. After this implementation, he found it easy to scale his service based on the type of consumers and there were no more DDOS attacks.

Figure 8 – Analytics and Reporting features in API Management Solution

With this implementation of policies, security, groups in the API Management Solution, and with the features available for generating reports and analytics about the usage, John’s company got full control over their service usage and began expanding their operations with more consumers on-boarding with more confidence.