The Challenges of API Drift: Keeping API Descriptions and API Behavior in Sync

API descriptions such as OpenAPI are describing what an API is doing, right? That's the theory, but since the description is a separate resource, in practice oftentimes an API does not behave as described. How often, you ask? There's some interesting data out there...

Listen to ‪@apicontext‬'s David O'Neill talking us through their recently published white paper about real-world APIs, their descriptions, and their actual behavior. Here are some interesting findings:

❗️ Only about half of all APIs investigated had an authoritatively published API description.

❗️ Only a quarter of the described APIs perfectly behaved as described.

❗️ OpenAPI description versions out there are a mix with 2.x still being used widely but 3.x and even 3.1 catching up fast.

What are your takeaways? Describe your APIs. Make descriptions easy to discover. Make sure your APIs behave as promised by their descriptions. Update your descriptions regularly and also consider upgrading to a more modern version of the description language. Find the full report here:

👉 ‪@apicontext‬: "The Challenges of API Drift" - https://apicontext.com/resources/api-...

#api #apidesign #apidescription #openapi ‪@OpenApi‬ #apigovernance #apitesting #apistrategy #devex