An Eye on the APIs: A Cloud Platform’s Role in API Documentation, Administration and Governance  

There is a very popular movie genre we might call “the heist.” We’re all familiar with it from movies like Ocean’s Eleven or The Italian Job. Pick any heist movie and you will see one obligatory scene. There is a small dark room where a security guard is watching 50 surveillance screens and the thieves either have to tap into the screens or they have to distract the guard. Somehow, they must not be seen on those screens. It seems like the number of screens would be helpful to the guard, but in reality, the theft is probably made easier by the fact that there are too many screens to watch.

Now imagine for a moment that you are a thoughtful system administrator, attempting to “know” your system’s ins and outs and connections. Daily, however, hourly perhaps, others are adding to the network of connections with their integration points and APIs, all seemingly harmless but incalculably numerous. You might feel like the unfortunate security guard. How can I keep my eyes on all of these screens at once when anyone can enter the building at any time and wreak havoc because they all have the keys? It isn’t just a security issue, it’s a system management issue. Who is keeping their eyes on the APIs? 

In our last cloud blog we discussed the rapid proliferation of APIs and their unwieldy nature. We talked about API traffic and how as APIs grow in number, network flow and data traffic will be an issue without the right approach. A cloud API platform solves this approach, but it also solves two other key issues, one of which we’ll discuss today: API management.

API management includes dozens of tasks and roles, but today we’ll focus on documentation, administration and governance. Admittedly, most people don’t get excited about these things, but they should! They are key concepts that when used properly give us incredible results. A well-managed cloud-based API platform approach will remove many time-wasting, head-scratching moments that we would have if we were still trying to watch 50 screens to keep an eye on the system. Let’s look at these features in detail.

APIs in the cloud: A system that documents itself. 

Without an API platform-based approach, you run the risk of a network ofconnectivity where the systems and functions are too complex to understand the impact of changes. When you end up having to either upgrade a particular API or troubleshoot it, it becomes an exercise in network engineering. There is no schematic. It’s like hunting for the right wires in a circuit board. Simple APIs lose their simplicity as they multiply with no documentation or governance.

Modern API gateway and API management toolkits have acknowledged this issue and they are built to assist the documentation step with some levels of automation. The API gateway “wants” to keep track of all that is happening. As APIs are introduced, the gateway captures the definition of the API in a machine-readable format that supports reference documentation. The gateway also enables the integration of definitions into the software development life cycle (SDLC) that will help to drive automation and configuration across the enterprise.

It’s as if the API gateway knows that the purpose of documentation is to save time, so it not only acts as an excellent reference tool, but it assists in deployment. Let’s look at a simple example.

Let’s say that I am a consumer of an API. I need to use a particular API from a certain company. If a platform doesn’t exist, then I am often forced to sift through an inventory of thousands of listings to figure out which one addresses my needs. This is like sifting through the Yellow Pages to find an Italian restaurant, only its even slower than the Yellow pages.

With the modern API management toolkit, there is a very robust system-driven documentation library, which can be searched with some dynamic search and discovery capabilities. It’s as easy as a Google search. Just like using a Yellow Pages is obsolete, not having a platform approach to API documentation is also obsolete.

The API platform-based approach brings order to the chaos because the system knows and understands the APIs and their relationships to one another. And, it’s smart enough to be able to share its knowledge with us. As we mentioned before, it isn’t just that we can now find the information easily. The API gateway acts as a bridge from documentation into deployment and use within the SDLC.

API administration: An eye on understanding APIs with precision.

An API gateway in the cloud makes API management and administration possible. It also makes it understandable. Once you have a robust, searchable, dynamic library, you are suddenly open to seeing the API world through new eyes.

For example, dashboards improve. (Fewer screens with more concise information.) You can tailor views based on what you need to know. You focus on the right details. You can monitor how each of the APIs is performing. It’s almost like the API gateway begins to talk to you.

“Hey, listen. Across the board, for your thousand API’s, this is your composite, fine grained data, measured by those 10 metrics that you feel are super important.”

Within an API gateway, we receive a much cleaner, precise and synthesized view of how the API system is doing. Once configured, it’s automated. It pulls in information. It displays it. It can route it. It can run deployment tests prior to release. It can truly manage many things without the administrator. Insurers won’t see this in a non-cloud, non-API gateway environment.

API guardrails: An eye on roles and responsibilities.

An API environment needs a division of responsibility. Let’s use an example outside of APIs.

Let’s say I decide to go shop for a car. There is one that I think I would like to buy. The salesperson and I are standing on the showroom floor and I’m looking the car over. I want a deeper look at the car, so I open the hood and look at the engine. That’s okay, but let’s say I’ve brought my toolbox and I begin to use my tools to remove major components and modify the mechanics of the car. I’ve stepped over a line, right? The salesperson protests, “Sir, please don’t take our car apart.”

Part of API system security involves maintaining a stable environment that might mean keeping my hands off of the vital systems of the API management that should only be touched by a qualified developer or administrator. 

We see this all the time and it is a real issue. Where an organization has a hodgepodge of a thousand API’s, and everyone feels they have free license to do whatever they want, the vital structure is in jeopardy. We need to keep our roles straight. It’s like our car. Who manufactured the car? Who is buying the car? Who should be allowed to work on it if we want to modify it? Some lines shouldn’t be crossed.

In our case, we have:

the person who is creating the APIs.
the people who need to configure an existing API to suit their specific needs, either for their customer or some other ecosystem partner.
the API consumers themselves who say, “I need a particular functionality that does x.”

Those are, in essence, the three roles and then you have someone who’s administering it horizontally across the board. An API gateway provides very defined access to each one of these personnel on what they can and cannot do. So, only the API creators can access what is called the API Developer Toolkit, which is where all the engineering things happen. It’s under the hood of the car. The gateway provides very delineated access and administration capabilities that are defined by your persona for what you want to do with the overall API ecosystem.

The alternative is problematic. You might have someone who’s supposed to be a user, receiving access to tinker around with the code to the programmable elements of the API, and they make an unwanted and unwarranted change. If this happens, versioning compatibility will somehow need to be banded back to the base function. It creates a complete mess, top to bottom. It’s not just about easing the access for a role or a persona. It is also to ensure that their guardrails are so well defined that they cannot do something they should not be doing.

API governance: An eye on the importance of API standards

Governance is simplification and security through consistency. It is tough for developers, users and administrators to stay on the same page. It can be more difficult when the environment continues to scale up rapidly. How can we determine the correct paths, methods and protocols that will help us to grow without losing efficiency? We define and implement standards. We ask the API gateway to assist us in our task by keeping us consistent and “on standard,” every step of the way. The API gateway is good at this. API Policy Enforcement utilizes many of the same protocols, definitions and methodologies that we have enabled during documentation to unify our teams in their approach. API Policy Enforcement keeps the environment clean so that everything else it does, including enterprise security, traffic control, workload optimization and monitoring, is much easier.

Customer impact: API governance brings agility to the business

API governance is very much about placing people, technology and processes in a position to flow unimpeded. Efficient API flow, regardless of how many APIs are in use, enables digital insurance environments to do more than ever before. This is how it ties back to the business. With proper documentation, administration and governance, the insurance business user will hit fewer hurdles as they create the products and experiences customers want. The API gateway is the kind of cloud-platform technology that simplifies and improves the API experience as it facilitates every communication and transaction it touches.

Majesco’s API Platform in the cloud removes the hurdles of API management and use. It takes the stresses of API growth and networking off of insurance organizations and enables them to use APIs to the fullest — whether that means deriving meaningful analytics from data or opening new revenue streams through channel partners or unlocking new third-party capabilities within an existing product. Utilizing Majesco’s cloud capabilities for APIs will launch a new era for insurers and catapult them into the future of connected, digital, real-time insurance.

You can learn more about API platforms in the cloud by familiarizing yourself with Majesco CloudInsurer® solutions, and join us in our next Cloud blog when we discuss the development steps of an API platform-centric organization.