Document and authenticate your way to API management success. Here are key elements of a sensible strategy to help you get the benefits of APIs without the headaches.
APIs are the backbone of every modern application, from web applications to mobile apps. They are essential to integrated applications, and many companies have dozens -- or even hundreds -- of APIs built around their core business services. A cloud API management program will ensure that these resources work to speed transactions and communication rather than becoming continuous nuisances.
With the popularity of microservices, it's easy for complications to arise with APIs that perform duplicate tasks, such as authentication. This leads to duplicated development efforts and conflicts when something needs to be changed in multiple places, as when an organization changes login requirements from usernames to email addresses or when it updates permissions.
To help development teams manage APIs, a company might consider centralized code and wiki documentation platforms or even automated API registration and management systems. Several open source projects have been developed, such as Tyk and Serverless Framework, and companies -- including Apiary, Kong and MuleSoft -- offer related products to assist with management efforts.
In general, good cloud API management boils down to three essential tasks:
security and authentication
monitoring and alerting
discovery and documentation
Security and authentication
Securing APIs is an important but frequently overlooked task. Most APIs will share a common method for request authentication. This could be OAuth, JSON web tokens, or just basic API key authentication. In some cases, the API gateway layer will handle authentication, simply passing through to the API whichever user or device is logged in along with the corresponding permissions. This API gateway layer will often call a specific authentication API with the user's request in order to authenticate it.
It's important to document not only how to use the API, but also which team owns that API.
It's important to note, however, that even if an API assumes it is behind an API gateway, it still needs to protect against malicious API requests that might not have originated from the trusted gateway source. Typically, this is done through a combination of firewall rules and access control policies. With AWS API Gateway, this can be handled through the use of identity and access management (IAM) permissions, verifying that any given request came only from API Gateway -- and preventing any other requests from hitting the API (or Lambda function) directly.
Similar authentication methods exist for most cloud API management platforms. Also, it's important to validate these security practices to make sure the APIs don't simply rely on the assumption that all traffic is from good actors. Every API should be tracked and monitored separately to regularly test for vulnerabilities. Assume all traffic is from an unknown source until proven otherwise.
Monitoring and Observability
Most APIs rely on outside connections. The authentication API probably relies on a database, and most APIs probably rely at least initially on the authentication API.
If the recommendation API fails, the developers in charge of that need to be alerted; still, that doesn't mean the entire platform is broken. Operations teams need to be able to know which APIs exist in order to monitor them and provide proper alerting. If the recommendation API fails but no one notices until a customer complaint comes in, admins will have a much more difficult time trying to track down when and why it broke.
Many API tooling platforms provide some sort of mocking system as well as common status checks. At the very least, an API gateway provides support for monitoring failure events; when something goes wrong, developers can be informed before customers start to complain. These additional details available within API gateway logs can help identify which part of the API is having issues. For example, when a customer isn't able to get recommendations, it might be because the authentication API is down. Or maybe it's just that the database connection to identify which past movies they've viewed isn't working right now.
Sometimes APIs can fail without customers noticing. In our recommendation example, chances are the front end will silently ignore that it can't suggest personalized recommendations; it instead will show things by most recently updated. Customers wouldn't be able to report this error, but developers should be notified.
In addition to passive monitoring of APIs, registering all APIs in a single place allows development teams to apply active monitoring of those APIs. Sample traffic patterns and edge cases can be added to integration test platforms to verify that the correct behavior will occur even when there's little usage. The Postman tool allows developers to build out sample documentation and mock endpoints as well as to continuously monitor APIs -- all within the same platform.
Mock endpoints can be useful for developers who do not yet have access to your platform. For example, a new developer might choose to use mock endpoints when first starting to build integration with their application, which wouldn't cause any strain on your production servers. If that developer proves that the application can work and won't cause undue stress on your infrastructure, you can opt to give him or her production credentials.
Discovery and Documentation
Authentication and authorization aren't the only things that APIs share. Oftentimes there will be communication with end users. For example, an application that sends text message alerts to users when a new product is available for them might also send them a message when someone logs into their account from a new location. Both systems have a legitimate reason to contact customers, but what about if users decide they want to be notified by email instead? If that code was written by two different development teams, chances are they didn't use the same API.
Having all APIs centrally available and well-documented allows teams to share common code for such things as user notifications. It shouldn't matter that one team is working on product recommendations and another is working on security. Both should be able to find and use the shared API to notify users.
In small organizations, it might be easy enough to ask other teams if anyone has started working on a particular task before. In a large organization with complex applications, it becomes increasingly important for teams to be able to locate this type of information themselves -- especially if they are going to make any sort of progress toward their effective cloud API management goals.
Just as GitHub made it easy to find out if anyone has already written an open source project to solve a particular problem, centralized API discovery and documentation platforms help development teams identify if anyone within your company has already solved a particular problem. Don't write the same notification API ten times. When you're doing that, your cloud API management practices are not up to the task.
There are many ways APIs can be documented and made discoverable by different teams via many different methods. Postman, for one, not only offers ways to provide mock API endpoints, it also shows sample request types, full documentation of an API endpoint, and searching or discoverability through online and protected portals. Additional methods include things like a shared repository with Markdown files for documentation, domain name system-based API registration and wikis. Open source teams often rely on Github, as it's already a place that people turn to when trying to solve problems and includes built-in error reporting.
Developers often work best in small teams, no more than five people on an individual team, and no more than a few related projects for that team. When APIs are split into microservices and can be shared among multiple teams, it's important to document not only how to use the API, but also which team owns that API.
Open source projects have worked this way for decades. And when companies evolve to include dozens or hundreds of APIs, it's important to think of them the same way -- anyone can help and contribute to a particular API, but someone needs to be responsible for maintaining the integrity and stability of it.
