API governance is a serious issue for enterprises rapidly scaling their digital programs. How else do you build a suite of dozens — or even hundreds — of APIs, while ensuring they remain secure, performant, and consistent?

It’s easy to think of API governance as nothing more than a collection of organization-wide standards for API design, but there’s more to it. In particular, getting API development teams to actually implement the standards laid out within your governance system is a challenge in and of itself.

In this article, we’ll look at how PayPal has maintained consistency across its sizable portfolio of internal and external APIs with the help of API governance. We’ll focus on the four-step process they use to develop governance-friendly APIs, as explained by Jayadeba Jena, PayPal’s Head of API Design, at the 2018 Nordic APIs Platform Summit. But first, what does “governance” mean to PayPal?

What Is API Governance at PayPal?

Before explaining PayPal’s process for governance-friendly API creation, Jayadeba introduces the five crucial aspects of API governance at PayPal: business capabilities, design principles, standards, object definitions, and versioning policies.

Business capabilities are the starting point for governance, describing what customers want to do with PayPal. As an online payments system, common capabilities for PayPal APIs are handling payments or creating checkout flows, but there are several others, like tokenization or invoicing. These capabilities will help to determine whether an API should be built.

Then, there are the principles that drive API design at PayPal. As you’d expect, these are the quintessential principles of effective API design, such as:

• Loose coupling
• Encapsulation
• Stability
• Reusability
• Contract-centricity
• Consistency
• Ease of use
• Externalizibility

Standards are specific design criteria that result in the principles outlined above — they’re what comes to mind when you think of API governance. They describe everything from URI structuring to operation behavior, as well as idempotence, authorization, and error handling… and more!

Another important part of API governance is object definitions. These are organization-wide definitions for handling common objects, like dates, currencies, and countries. Where possible, PayPal strives to use ISO and industry standards to define these objects, promoting API compatibility both internally and externally.

A belated addition to PayPal’s governance model was a clear versioning policy. This includes specific criteria on what it takes for an API to be backward-compatible, as well as guidelines on how to iterate, like what to break and what not to break. It also detailed end of life policies, such as the timeframe between functionality deprecation and retirement.

You can see PayPal’s design standards, object definitions, and versioning policy in their publicly-available API Style Guide. Speaking of which, be sure to create your own style guide as part of your governance program, so that development teams can easily reference design standards during development.

The Four-Step Process for Building Governance-Friendly APIs

Having a comprehensive framework for API governance is just one half of the battle; the other half is implementing it! This is where PayPal’s four-step process for API governance, as detailed by Jayadeba himself, really comes in handy.

In a nutshell, every API goes through four phases: Define, Design, Develop, and Externalize. Each phase features feedback from the organization’s central API design team, ensuring governance standards are closely followed.

1. Define

Every API starts its life with a proposal, which defines what the API does and who it’s for. This provides a thousand-foot view of where the new product will fit into PayPal’s existing portfolio of APIs.

The central design team reviews this proposal, ensuring that it corresponds to one or more of the organization’s business capabilities (as laid out earlier). Equally important, the team also checks for any functionality overlap with existing APIs.

If everything adds up, the team sends back any feedback and creates a new repo for the project. Then, the API moves to the next stage.

2. Design

This next phase — the Design phase — involves fleshing out the new API using the OpenAPI Specification. The specification covers just about everything, including URIs, parameters, sample responses, and more.

The complete specification goes back to PayPal’s central design team, where it’s checked against the governance framework’s API design standards. After addressing any issues, the API goes into development.

3. Develop

Next, the development team begins building the API according to the approved specification. This is where any oversights, such as unforeseen error cases, become apparent. As a result, iterating on the original specification is almost a must.

Importantly, not all of PayPal’s design standards will have been accounted for in the specification. As a result, undefined design issues (like how traffic is logged internally) are covered at this stage.

Once development is done, the API goes through a series of functional tests, which ensure that the implementation is identical to the contract — i.e. the specification. After fixing any errors, APIs move to the last stage.

4. Externalize

Last but not least, the prototype API is externalized. As in the development phase, certain API characteristics which are covered by the organization’s design standards, but not the specification, are now built.

Security measures such as authorization and rate-limiting are implemented; SDKs are built, and developer-facing documentation is written. All of these areas are reviewed by the central design team for compliance, and the API is ready to go!

A Note on Scaling

It’s worth bearing in mind that the process Jayadeba explains revolves around a centralized API design team. He admits that this central team quickly became a bottleneck at PayPal, as the API program scaled.

The solution was to train product owners to review their development team’s work against the organization-wide governance criteria. The central API design team was still responsible for developing the governance criteria, but they were no longer tasked with reviewing each and every API.

Final Thoughts

There’s more to API governance than creating a set of design standards. In fact, an important part of any governance program is a watertight process for ensuring design standards are actually followed. PayPal’s four-stage process for API creation — Define, Design, Develop, and Externalize — ties into the governance program at every step, ensuring a consistent, organized portfolio of quality APIs.