Category: api best practices

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, "Do you have any concerns regarding the current state of API management?" Here's what they told us:

Design-First

• A lot of great tools have become available for building and deploying APIs. However, design-first has not become as widely adopted as one might hope. Many times, developers are asked to provide an API, and they do just that. The person making the request for an API may have a very narrow need, and the developer can easily throw something together to satisfy that need, but then later additional users access the API and it comes up short in some way. 
• One issue that might arise is the slow down of the applications. In some cases like creating an account, it's not unusual to have to communicate to multiple APIs to notify the action. For instance, sending a request to the analytics API, another to the payment processor to add the new user, one to add this new user to the chat & support service, and finally, one to send the welcome email.
  
  If these requests are made when creating the account, this can sum up to initial requests that can quickly take a few seconds to complete and might cause issues down the road. (What if the first two requests were successful, but not the last one? How can we retry them? Which one to prioritize?). That is why having some asynchronous call to external APIs implemented whenever possible, with retry mechanisms and alerting system in place a great way to mitigate these issues. 
• The primary concern is that the market is ripe for consolidation. Solutions that are only 5-10 years old already have a “legacy” architecture that can’t keep pace with new architectural patterns like microservices. Customers need to be careful they don’t build their API capabilities around a solution that will need to be ripped out and replaced in just a few years.

Version Management

• Dealing with the API contracts and open-API specification that tells you what an API can do. Version management or version changes to the APIs is still a challenge. Ways of communicating grow exponentially not a great way to handle. Moving so fast with features consumers have to support multiple versions at once.

Lack of Best Practices

• A lot of progress has been made in the last few years. The big cloud providers are doing more. There's still a big learning curve for new developers. There are a lot of APIs out there that have not used best practices. For the development of new systems, the integration of APIs is still a big concern. 
• So much of API management is still externally focused when there’s tremendous value in internal use cases. Focus on building a program internally that focuses on your internal developers. Give internal developers the information they need to take advantage of the services and get out of the way. Help your developers get their job done. If you create that portal for your internal audience where everything is well-documented and you’re guiding them down the path to get stuff done, that has a long-term benefit for internal teams and creates an innovation strategy with less fear of failure.
• Too much of customer work is still required to put a good API product together, the vendors’ layout might be complicated and unintuitive. Lots of terms and product categories are fairly new and non-standard. As publishers switch their focus from a need to publish and focus more on the developer experience of the consumer, things will improve.
• The lack of well-documented standards, especially when it comes to API versioning.

Other

• How do you strike the balance between flexibility and optimization?  The public cloud is a good place to get started with small amounts of data but with large amounts of data, it starts to get complicated. We’re working to solve the throughput model of current APIs. Work is still needed on that front. With a microservices architecture, it gets more complicated as one service depends on many others. Tools like Istio and LinkerD become more important for circuit breaks and timeouts otherwise it just becomes a complete mess.
• API management is a somewhat mature area. Key functionality blocks are pretty clear – gateway, portal, analytics, monetization capability, the key-value today is how effectively these pieces integrate together to deploy and get value from the API infrastructure. 
• The domain is striving: complementary tools, techniques, practices, actors appear regularly - while existing ones are still being improved. The days when it was unclear whether selling an API could be a good idea, are long gone.
• I think that there is often too much of a focus on quickly "pushing" APIs out and getting them online, without a deliberate effort to create a solid API-first culture. Runtime considerations such as security are certainly important, but everything that occurs before an API is deployed and running in production is equally important and often overlooked. 
• Current APIM tools are heavily focused more on the provider and the consumer is an afterthought. We want to empower the API developers to know how many requests have been made by consumers in a given timeframe. We also want consumers to be able to handle situations such as an outage, API changes or retirement, etc.
  
  There usually is not a clear method for developers to communicate this information to the API consumers in a timely manner and the latter is oftentimes left in the dark.  Exposing this information is becoming more vital in today’s API economy. In addition, the lack of testing of an API (Contract, Automated, etc.) is something that will also need to be addressed. Implementing proper testing will ensure less likelihood of changes in the API breaking integrations, reliability and an ability to test at scale. 
• API management is not something new. The old-style gateway is out there. It’s hard to manage. The trend happening in the market you see next-generation API gateway much lighter and endpoint as a proxy, open-source to see what’s going on, familiar with the microservices era. Using K8s backup by default. People are misrepresenting what their platform will do – suggesting they can facilitate microservices while they’re still running legacy, monolithic applications. 
• We’re about a decade into the microservices era, but there’s still a paucity of tooling and practices to support companies who are delivering microservice APIs directly to customers.  At a standards level, the only option the OAuth2 spec provides is Scopes, and these are woefully inadequate for microservices APIs.  In anything beyond a trivial deployment, you need to reason about the resources a caller can access.
  
  The lack of standards around this makes authorization and access control a problem without a common solution, so everyone is left to roll their own or code to a vendor’s design. Given the asymmetry of changing API interfaces (and your access model is an absolutely critical part of your interface), we’ll be stuck with these proprietary implementations for years to come. 
• Many API cost estimators are available, and few people understand the long-term costs they are imposing on themselves and their customers through their APIs. A conservative estimate is $25K to build an API, and $15K for your customer to integrate to it. Plus 50% annually to maintain it. This means an app with 100 APIs being consumed by 100 of your consumers is generating about $15,000,000 of cost mostly to your customers.

Here's who shared their insights: