Any business operating at scale eventually comes across the need for standardization – a set of shared and accepted guidelines that assure that all products or services are delivered to the same consistent standard. This principle holds true for the API industry.
For over 20 years, Amadeus has been offering thousands of APIs that underpin the global travel industry. Last year alone, we received over 500 billion API requests. Which such a volume and variety of APIs, designers and consumers in the mix, it’s crucial to offer a consistent experience. That’s where API governance comes in.
What is API Governance?
API governance is the practice of creating, applying and maintaining common guidelines about how APIs are designed. Its primary function is to ensure that customers find consistency among a company’s APIs and that internal designers and developers have a clear and common path to creating new ones.
In practical terms, API governance is a community of API designers, developers and subject-matter expert (in our case, travel) who get together regularly to share best practices for API design, agree on new standards and review and validate new APIs.
At this point, it’s also important to note that API governance is not a bureaucratic control entity. Rather, it’s a democratic approach to API production – one which, in the end, supports API design by making the process faster and more agile.
Why you need API Governance
API design governance can be a win-win for both designers and end users. From a designer’s perspective, good governance helps teams to:
- Reduce errors by assuring that the common guidelines are understood by and accessible to everyone.
- Standardize data dictionaries and versioning so teams aren’t reinventing the wheel with each new or updated API.
- Standardize endpoint and parameter naming which helps create an organization-wide ecosystem that makes it easier to integrate new APIs into larger, more complex flows.
- Improve continuously and globally by making best practices accessible throughout the organization, reducing discrepancies among teams and streamlining the review and validation process.
From a user perspective, maintaining consistency among use, models or endpoint and parameter naming makes your APIs easier to understand, especially when you’re dealing with a highly complex internal backend and logic. Once a user has integrated one of your APIs, it becomes easy to understand and integrate others.
5 best practices for effective API Governance
Now that we know the what and why of API governance, let’s look at some best practices we’ve learned at Amadeus to help your initiative be as effective as possible.
In our experience, having a single, centralized entity responsible for creating and maintaining API design standards is key, especially for large or complex organizations. In the same vein, make sure your documentation – guidelines, common models, etc. – are kept together are easily accessible to everyone in the organization.
To avoid having your centralized entity become a stifling bottleneck, make sure your governance board meets regularly to review new APIs, update the guidelines and data dictionaries and keep the workflow moving forward.
Provide continuous training
API governance is intended to support good API design, so ensuring that designers are up to date on commonly agreed best practices for naming endpoint and parameters, managing use cases and handling operations and resources is key to continuous improvement.
Have the right tools in place
Shared tools create common procedures that ensure that the API creation process is followed correctly. We have a custom tool integrated throughout the review and validation flow, including review cards to keep track of comments and decision logs which record updates to the guidelines.
Just as common tools and processes are key for successful governance, instilling a common mindset among board members is also important to make sure everyone is one the same page. At Amadeus, we use the HAPPY Principle:
- Homogeneous – all APIs should look the same. This benefits the consumer and helps reduce internal complexities.
- Active – all API Governance members are expected to and contribute and play an active role.
- Pragmatic – above all, focus on what’s useful. This requires looking beyond your specific project requirements and thinking about the benefits for consumers and other internal stakeholders.
- Positive – constructive opinions only. This is key to keeping API Governance productive and avoiding tug-of-wars.
- Young – mentally speaking, at least! API Governance can evolve, and it’s important that members never stop learning and bringing new ideas to the table.