You never get a second chance to make a first impression. An API is often a developer’s first point of contact with a software-as-a-service. It must perform as expected, or you risk leaving a bad impression that stays with them. Delivering a sub-par developer experience can lead to negative feedback and a subsequent toll on your brand reputation. At worst, it can cause API security issues and, in some instances, even cause legal issues.

Unfortunately, APIs don’t always behave as they should. APIs have a tendency to get away from their specifications, sometimes due to a lack of regular upkeep. When this occurs, the specification doesn’t match the production behavior, causing issues. This is known as API drift.

API drift is a common phenomenon, as reported by APIContext in their recent white paper OpenAPI Specifications in the Real World, featuring research based on 650 million API calls to more than 10,000 different API endpoints. Here are some of the key findings, which should underscore why API teams should always keep their API specifications up-to-date.

75% of APIs Have Nonconformant Endpoints

According to APIContext, 75% of production APIs tested had variances to their published OpenAPI Specifications. As APIs are developed, they may drift away from API specifications, no matter how detailed they may be. Certain types of APIs are more prone to drift than others. Certain banking, fintech, and bulk email management APIs showed 0% API drift. Some other APIs, like those from Box or Pivotal Tracker, had a much higher API drift rate.

Some of the most common errors include:

• API returns the wrong format
• The API returns the wrong data
• The API resolves ambiguously
• Poorly defined pass/fail criteria

For the wrong format errors, APIContext recommends returning structured objects as either null or empty as a best practice. For value errors, they recommend returning an HTTP status to make debugging easier if there’s a problem.

43% of APIs Don’t Have A Public API Specification

After searching common terms like ” OpenAPI Specification”, APIContext discovered that only 57% of APIs have public API specifications. A public API specification is an important aspect of delivering a positive developer experience. It can also facilitate API integration and automated API documentation. Last but not least, a public API specification is an excellent opportunity to market your API.

Source: APIContext

Most UK Banks Don’t Customize Their Open Banking OpenAPI Specification

Even though UK banks are required to adhere to specific UK open banking API standards, many don’t go the extra mile with their OpenAPI specifications. Not doing so could cause errors and be a missed branding opportunity.

Individual banks can customize their specification to their specific hostname, which is the base URL of a service. For one thing, providing documentation containing specific endpoints lets users know exactly how to use the API. It’s also an excellent opportunity to show users that a banking API is up-to-date, secure, and well-maintained at the same time.

OpenAPI 2.0 Still Shows Significant Use

OpenAPI Specification (OAS) 2.0 is still a popular API specification despite being published roughly ten years ago. 30% of the APIs examined by APIContext were still using OAS 2.0. Of the 54% of APIs using OAS 3.0, minor versions 3.0.0 and 3.0.1 are the most common. Not many (7%) use the latest version, 3.1.0, which was released in early 2021.

The use of older OAS versions is partially due to some service providers acting as a bottleneck for updating an API. For instance, AWS Gateway doesn’t support OAS 3.1, and Google’s API gateway only supports OAS 2.0.

52% of APIs Haven’t Been Updated In Six Months

APIContext discovered that over half of API specifications hadn’t been updated in over six months. When API specifications are updated, they’re updated as often as every few days. This discrepancy illustrates the different attitudes towards API specifications. Those who update their spec regularly see it as part of their development cycle and as a best practice for API upkeep. Those that don’t update regularly have a different philosophy about specifications.

Without OAS 3.0, API developers can’t leverage new features, such as OpenAPI Links, which describes the relationship between responses and operations. They won’t be able to use OAS 3.0’s reusable components, either, making it more cumbersome and time-consuming.

Finally, without upgrading to OAS 3.0 API, developers can’t take advantage of the specification’s latest features, such as greater handling of asynchronous APIs or Webhooks. Yet, not wanting a JSON schema to be prescriptive is the most common reason for not updating an OAS regularly. Reliance on legacy service providers like Google API Gateway or AWS Gateway is another common reason.

Final Thoughts on API Drift

APIContext concludes its report with some best practices to avoid API drift. To start, they recommend making your OAS public and discoverable, preferably with a direct link or GitHub Repository that is updated regularly. They also recommend testing your production APIs against the published spec, which should help keep API drift to a minimum.

Inaccurate and unreliable APIs play a large part in some users’ unwillingness to adopt APIs. So, ensuring your API adheres to its specifications will help encourage API adoption, as developers will know they can trust the API and that it’ll work. It also helps reduce the risk of alienating potential users and customers, which can negatively impact your brand reputation while simultaneously boosting your API security.

API calls make up over 80% of all internet traffic, according to Akamai data. Arguably, the surge in API usage in the last decade has a lot to do with the adoption of standardized API formats like OpenAPI. They’re an important part of everything from API testing to eliminating shadow APIs.

Given the importance of accurate API descriptions, a broader emphasis on the benefits of regularly updating an API specification would be a huge step forward in reducing API drift. Considering how much you stand to gain, and how much you have to lose, there’s every incentive to avoid API drift by keeping your API specifications up-to-date.