Embedding Good API Practices in the Enterprise


APIs have become a critical tool for any business looking to digitize services, processes and operations. However, as the number of APIs grow so too can issues around security, efficiency and performance without the appropriate API governance in place.

Unfortunately getting buy in for API governance from business and IT stakeholders can be easier said than done. Some of the typical perceptions we hear from those who bypass the API governance layer include:

  • “We need to put this into production tomorrow”
  • “I just need a quick point-to-point file upload”
  • “The payload must be ‘dynamic’ so we don’t apply a contract”

In this blog I’m going to share some learnings on API best practices to help you build a lightweight governance layer that will improve experience across the enterprise and maximize the benefits of APIs for your business.

Ensure your API Gateway Covers the Basic Patterns of API Governance

With so many API tools available in the market, it can be tempting to use price as the critical determining factor for technology selection. However, to ensure longevity you should also ensure your API Gateway has the following core capabilities to cater for the basic patterns of API governance:

  • API control and auditing
  • API security
  • API monitoring
  • API versioning
  • API development lifecycle management (publish, discover, maintain and oversee APIs)

Without these capabilities, you can run into all sorts of issues as the number of APIs in your technology landscape grows. For example, without a mature API versioning strategy and concurrent technology ability (implementation pattern), the consumption of APIs might start off with a bang but fade as new versions of the API are incorrectly introduced leading to consumption difficulties.

Maximize API Invocations through the API Governance Layer

Resist the temptation to do a ‘point-to-point’ interface without the API Governance layer involved for a technical, timeline or some other reason. Instead, make as many API calls as is feasible through the API Governance layer. This will allow you to effectively govern much of the enterprise API experience via one mechanism (pattern). This is especially important with APIs calling other APIs and even in the case of publish-subscribe or asynchronous patterns, and will enable you to proactively manage dependencies, a hallmark of a good microservices environment.

Enable and Enforce Self-Administration Capabilities

It’s important to enable the self-administration capabilities for the API consumer as far as is feasible to minimize possible disruptions in the future. For example, rather than generating keys on behalf of API consumers and sending it to them via less secure channels you should ensure they can generate new keys themselves. This capability can become critical in an event such as an API consumer system being compromised and their API keys being exposed. Rather than waiting days for a service ticket or being dependent on another team for configuration or deployment, the consumer would be able to apply new keys almost instantly.

Apply Contract-First Design

You should always create a proper contract and adhere to that contract e.g. OpenAPI specification or RAML. A well described contract including descriptions, example values and data types even if fine-tuned across various agile sprints, ensures there is less misunderstanding about the function of an API between consumer and API provider.

Balance the API Consumer Needs with Feasibility and Performance

According to reports, 74% of API consumers experience performance issues. This statistic correlates with what we are seeing in the industry around API consumption.

To optimize the performance of your APIs, you need to balance the needs of your consumers with feasibility, performance and security. For example, rather than providing all the required information in a single GET API response (JSON) payload you might separate out a sensitive subset of the data into a separate sub-resource API response and provide an href to it from the original, thereby improving security management of sensitive data and possibly also the response time to core critical data.

Applying these practices will improve the experience for API providers and consumers by reducing human operational effort and the usual overhead associated with point-to-point (and other non-API governed) integration patterns. Your business will also benefit through improved long term API consumption experience and faster time-to-value on new business initiatives due to streamlined API discovery.

Author Details

Riaan Ingram
Riaan is a Principal Consultant with over 20+ years’ IT architecture, design and development experience. Riaan has a strong technical, hands on background and specialises in developing and integrating enterprise business solutions. Riaan has in depth knowledge of integration as well as cloud patterns & technologies and is an expert in the planning, design and implementation of API first, event driven, microservices, low/no code integration approaches.

You might be interested in these related insights