7 API management challenges (and how to solve them)

APIs are a critical tool for building modern applications. But like all useful tools, you have to manage APIs properly in order to use them to greatest effect.

With that in mind, let’s take a look at the top seven challenges that arise when managing APIs. We’ll also discuss strategies for addressing each one in ways that ensure API scalability and resiliency.

Challenge 1: Re-engineering for the cloud

Chances are that if you have a codebase that is even just a few years old, it has a monolithic architecture, in which all application components run as a single program. Trying to modernize this architecture to be more scalable and cloud-native friendly is more challenging than it should be. It could involve excessive refactoring, adding new layers and error handling, and choosing the right format to serve to consumers. And while all this happens, the existing business needs to function, so there is additional pressure to adopt a hybrid service approach.

Fortunately, there is an easier approach to modernizing a monolith in a way that prepares it for a cloud-native environment. Instead of going through all of the steps just described, you can instead add one middleware layer (or another layer of abstraction) on top of your existing services that converts messages into consumable endpoints. The amount of work required depends on many factors, but the idea is to start small and expose gradually. Decoupling is the key here.

For example, Thriftly takes this approach and elevates it to the next level. By allowing easy transformations of existing programs and secure API proxies (among other features), it eases the process without destroying existing infrastructure.

Challenge 2: API documentation

Documenting an API is a critical aspect of making sure your API is fully adopted. It makes sense to make their lives easier by providing first-class documentation that is in sync with the current codebase. This can be done by providing a Developer portal.

Developer portals are tailored to provide an easy-to-read format for your API endpoints, terms of usage, community resources, and ideally, a live chat.

As an API provider, it's important to keep services available for developers by providing support, tutorials, code examples, and anything that can be used to explain the APIs you are serving.

It's also important to document everything, including unusual or special cases, and to point to issues with a ticket for follow-up. The happier developers are, the more likely they are to recommend your platform to other companies or developers in the future.

Challenge 3: Visibility and governance

Like all IT resources, APIs need to be effectively governed. This entails establishing a policy that determines how a given API can be used, which things it should not be used to do, which best practices engineers should follow when using the API and so on. Having a clear governance policy in place not only helps to optimize internal management of the API, but also makes it easier to comply with regulatory frameworks like PCI DSS, GDPR and others.

Ideally, the process for establishing a consistent governance policy that delivers organization-wide visibility into how a particular API should be used will start as soon as you begin designing your API. If you already have APIs in place but lack a clear governance policy for them, all hope is not lost. In this case, you might consider how other IT governance policies used by your organization could be extended to help manage your APIs as well. And if you have to write an entirely new governance strategy for an existing API from the ground up, that can be done, even though it’s not ideal to wait until after the API exists to do this.

Keep in mind, too, that effective visibility and governance require ongoing updates to API management policies. As your requirements change (which happens when, for example, new regulatory rules are introduced), or your API evolves in new ways, you’ll want to modify governance policies, too.

Challenge 4: API orchestration

You can manage a simple set of API endpoints easily enough by hand. But when you deploy APIs on a large scale, and run dozens of API endpoints served by dozens of API services, orchestrating all of these moving pieces manually does not work.

That is why, in order to use APIs at scale, you need to rely on a level of abstraction to manage and orchestrate groups of endpoints in order to achieve a more seamless integration with their clients.

The solution for this task is a piece of software called API Gateways. These are integral points that sit between the application servers and the reverse-proxies that provide tailored functionality covering several key factors that affect the API lifecycle.

Among them are SLA conformance via traffic throttling, prioritization or routing, API security rules, access controls, debugging and troubleshooting, protocol bridging and merging the content of several APIs into one.

As you have guessed by now, choosing a good API gateway should be a top priority, and it's important that it be extensible by design.

Challenge 5: Viable monetization

Being able to provide quality APIs for your end-users also includes having a reasonable pricing strategy that helps open new opportunities with customers, developers, and partners. One thing customers want is customizability and first-level support on operations or service-level agreements, especially when things go south.

Businesses need to offer a range of rate plans (typically three), with the option to customize them per organization. Sometimes an out-of-the-box approach can help with easier onboarding. You can add premium upselling channels once you are established or form new partners.

Challenge 6: API versioning

Software changes. So do APIs. So the best solution to manage change in your API is to embrace the fact that it won't be the same two years down the line. There are multiple challenges as well as community recommendations regarding API versioning, and when there are lots of ways to do things, it’s important to take time to put them into perspective. APIs must support both breaking and non-breaking changes in a way that does not hinder developers from doing their work.

It's not an easy thing to accomplish, but there are some recommendations, like using the URI portion of the contract to specify the version. For example:

http://example.com/v1/users
http://example.com/v2/users

This has some advantages, as it's easy to implement, but the most obvious disadvantage is that clients should know the structure or design decisions of the API beforehand.

Another approach is to use revision parameters:

http://example.com/users?version=1.1
http://example.com/users?version=1.2

This looks more complicated to implement, but offers more advantages in the long run. It is more fine-grained. and URI naming does not depend on prior knowledge. This provides a way to opt-in instead of opting out of any changes and adapts more harmonically.

The last approach is using headers. We could, for example, version the headers using a unique term:

Accept: application/com.example.app-v1+json

This is the most opaque way to do it. It introduces a few more implementation complexities because the clients have to add those headers in the request payload (they are not available in HTML format). However, it has some good uses in practice.

The whole idea is to have API consumers deploy clients that will not break, and API providers can make changes that will not break their clients.

Challenge 7: Security

If it’s on the internet, you need to secure it. Period. Adding security controls is necessary to ensure availability, confidentiality and integrity in their operations.

As part of a continuous improvement process, there should be a place for security considerations and tasks which cover the minimum threats, and industry standards like OWASP’s Top 10 Most Critical Web Application Security Risks can be applied.

Development teams and Operations should follow a security checklist and allow external vendors to perform penetration testing periodically. Integrating useful plugins into API Gateways like IAM policies which include RADIUS integration, access controls, or threat detection could significantly help Operations secure the most critical functions from breaches. In other words, you need to have a holistic approach to cybersecurity to mitigate risks effectively.

Final Thoughts

Companies moving to hybrid or pure cloud environments have to surpass some obvious and not-so-obvious obstacles along the way. The ideal scenario is to do the job without rewriting source code or core business logic. If you have legacy Windows-based applications that need to be migrated into the cloud, I suggest you take a look at Thriftly. It ticks all the boxes and lets you be flexible without having to make changes to the underlying codebase.