To gather insights on the current and future state of API management, we asked IT professionals from 18 companies to share their thoughts. We asked them, "What are the most important elements of managing APIs?" Here's what they told us:
Protection
- Since you are exposing APIs to line-of-business applications, they need to guard against abuse. With two-factor authentication. people try to do fishing attacks. Rate limiting, circuit braking, and timeouts become quite important. Our SLAs tie-in with the other systems they are interacting with. When there is too much load on the system, you need to think about how to shed load. Interesting rules come into play even with APIs exposed out to everyone.
- API lifecycle management consists of defining, publishing, securing, routing and mediating traffic, monitoring, and analyzing APIs. The two most important elements of managing APIs are:
1) API Security — according to OWASP Top 10 - 2017, “sensitive data exposure” by APIs is the third most critical web application security risk.
2) Providing a seamless consumption experience via a robust dev portal. According to the 2018 State of API Integration report from Cloud Elements, this is the second most common request from API consumers. - A lot of customers are interested in a different environment and may have moved to microservices which makes APIs a big piece. Security, rate-limiting be in control of how many requests you have. Canary deployment, green/blue deployment, A/B testing is very popular. Have one microservice with the old version of the API and one with the new API. Push the new one and route traffic from 10 requests — one in 10 go to new and then watch the metrics and gradually move everything to the new version. Have security on the gateway side to monitor traffic from the internet. API management is taking the operation logic away from the engineer or developer, it’s done in the proxy itself. The API gateway takes care of security.
- Security, then stability. If permission-driven rules are co-resident with the API code, then having an excellent process that keeps security in-sync with your changing data is critical. Secondly, stability, we want to ensure our API users remain backward-compatible.
Ease of Use
- There are many important elements to deploying APIs including authentication, protection/availability, and monetization. However, many of those don’t matter if the API is not adopted and used. Ease of use and successfully fulfilling a use case are key to gaining adoption. Our integration platform makes APIs easy to use.
Through our application connectors, we can simplify the use of the APIs of many popular software applications. On the API provider side, we give users a second chance to get an API right. A complex API that provides somewhat generalized access to a system can be simplified to satisfy a single important use case (i.e., get my order status). - The last letter in API is “interface” for good reason, and I’ve long felt that the most important thing is to clearly define how you expect that interface to work. How do customers consume your APIs, and how do developers bring those APIs to market? There are a few major architectural decisions you need to make upfront. First, are you planning to go all-in on microservices where your customers are consuming from hundreds or dozens of public-facing APIs, or are you going to wall them up behind a gateway or façade that reduces your surface area? We’ve chosen the former.
In our case, you need to put a lot of effort into ensuring standard practices (on everything from authentication to capitalization in responses). If all of your APIs feel like they were developed by different teams, you’re making it harder for customers to adopt more than one. What makes interface definition particularly critical is that a misstep takes years to unwind.
Once customers are consuming your API, you have limited scope to make changes without requiring your customers to recode their integrations. And every time you require customers to make a change, they’ll ask themselves why they are working with you and not a vendor that can get things right the first time. - Maintaining consistency in naming and data formats as the number of endpoints grow. It’s not a big deal when you’re providing 5-10 endpoints, but when number gets over a hundred you probably have multiple people (or multiple teams) creating them, over different periods of time, introduced as a part of different products, etc. Having an easy way for all teams to access existing specs is critical. If those specs would be long and difficult to read — it leads to problems.
Some questions about formats and conventions we expected to be already solved actually don’t really exist. It’s surprising how many ways are out there to describe sorting/multipage/searches/filtering with multiple parameters. Some standards exist, but after a deep look, we found them incomplete for our use case and had to come up with our own conventions.
Analytics
- Communication with visibility. Make it clear what the apps are and how to use them with design, documentation, messaging, and how you sell and market them. Well-designed APIs can fall apart if you do not communicate their value and capabilities. If you manage and own APIs, you need visibility into what’s happening with them, how they are being used, if anything bad is happening. Reports can indicate new and interesting directions in which to take your API program. Do this based on your own metrics and visibility. You have a better chance of succeeding versus copying someone else.
- Performance, reliability, and analytics are all important topics in API management. The operational quality of Facebook or Google progressively became the baseline for the delight of end-users and the doom of site reliability engineers. Beyond these, when creating an API-centric business, two rarely mentioned elements are of the utmost importance. The first is maintaining compatibility over time.
The purpose of APIs is to have customers build products leveraging them. An API whose form changes — breaks — regularly, alienates customers who have to update their own products in consequence. There are many ways to maintain compatibility while moving forward — versioning and backward-compatible changes being the most common. Yet to be done correctly, the topic must be considered right from the start. Besides, maintaining compatibility generates an extra cost, whether in the form of explicit infrastructure cost when old versions of an API must be kept running, or of implicit maintenance cost when old versions must be regularly patched if not just for security reasons.
Another major element of managing API is enforcing security while providing transparency. It is not just about ensuring that the correct people have the appropriate set of permissions to manipulate data anymore. That would be “conventional” security, and while it’s still very relevant and definitely not a solved problem, the topic is relatively well understood.
Today, customers expect understanding if not guarantees on the actual use of their data by the company delivering their services. Are their data indirectly leveraged — e.g. by “blind” machine learning algorithms? Can they request their old data to be removed entirely from servers? Can they access all — absolutely all the data their provider is storing about them?
API Lifecycle Management
- API Management has the following four major elements:
1. API Lifecycle Management — We believe providing companies the ability to manage the entire lifecycle of API - from designing, developing, publishing, and management of API (that includes retirement/versioning) - thus allowing companies to accelerate innovation by composing innovative solutions, facilitate better security of their enterprise data and allow users to discover and consume your APIs easily.
2. API Gateway — An API gateway acts as a point of entry for a set of APIs. Benefits of using an API gateway is providing the optimal API for each client, reducing the number of requests a client needs to make and enforcing appropriate security and controls.
3. Documentation — The Developer Portal is key to increasing adoption and stickiness of your APIs. It is your initial method of communication with developers. This is the first point where a developer learns and uses your API and is where the developer will learn about the authentication/authorization mechanism. In addition, they will learn which APIs are available for consumption and leverage descriptions and examples for each API request.
4. API Analytics/Monitoring — API Analytics and Monitoring helps companies learn and understand the utilization of their APIs, which can provide insights on the use of various APIs. Alternatively, companies can enforce API quotas, limits, and API traffic throttling to discourage/limit usage that doesn't align with your business goals.
Other
- APIs have transitioned from XML-based contracts like SOAP and WSDL to a RESTful format with a little loser definition, using JSON to communicate. Document how it works in a machine-readable format. Define contracts and make them easily consumable by humans and other APIs. Leverage Open API 3, describe APIs in JSON, communicate and understand what the API can do for you and how to communicate with it.
- In more than half of the projects, APIs are delivered by clients or third-party services. Make an alignment of deliverables when APIs are being developed at the same time as the application. People are still learning to design, secure, and deliver APIs. APIs are built to be used. When you design, fit the needs of the consumers. Be efficient for a specific use case. Backend APIs can be very different than for a mobile application. A lot of coaching is needed to help developers understand the best practices for APIs in mobile. New standards like graph QL helps with that problem. APIs provide more flexibility for the types and amounts of data.
- It is important to anticipate and integrate fallback when an API stops responding or starts to behave differently (like when the API is having a bug). Often, the issue could be easily mitigated by pushing the action to a queue that will be tried again later (like, for instance, sending an email or saving an action), but it's not always possible. Having the application handle such case and indicate with a custom message any issues to the end-user - along with some notification to the development team - is crucial to ensure a well-working service.
- There are the usual suspects at runtime, such as security policy management, telemetry and monitoring, and consistent performance. This functionality is more accessible than ever via a number of mature API Gateway products. The most important, and often overlooked, element of managing APIs at scale is a solid API design foundation. It's in developing an API-first culture within your organization that elevates their importance and provides a clear development workflow that results in higher quality, more consistent APIs.
Here's who shared their insights: