API Style Guide and Patterns: The Evolutionary Journey Continues
APIs as Products
Around four years ago, we began the journey at PayPal to transform all of PayPal’s core capabilities into a platform of discoverable, well-encapsulated, reusable API-driven products. We have used a customer-oriented approach to go from a very monolithic and siloed architecture to a much more loosely coupled set of over 150 services with well designed, modern APIs. We framed this transformational exercise as an organizational change initiative, with the goal of bringing a fundamental shift in how we design and build APIs. We made it a priority to identify and serve all key “customer” constituencies — developers who design and build APIs, developers who create innovative applications using these APIs, as well as the executives who support these efforts. This mindset influenced the strategy, the processes and the tools that we put together, our communication with the stakeholders, and the definition and measurement of success. An unflinching focus on developer experience and satisfaction has been key to our success, and it continues to shape how we manage this transformational program today.
While every company has its own unique culture and challenges, many of the very valuable and insightful lessons that we have learned, and the approaches that we have utilized, are applicable to other companies that are trying to chart the same course.
Principles
At the beginning of our API journey at PayPal, we started off thinking about what common ideas would guide us towards our goal of nicely encapsulated services that exposed well-designed, reusable APIs. These became our core principles and directed much of our subsequent standards evolution, as well as the criteria for measuring API quality.
- Loose Coupling
Services and consumers must be loosely coupled from each other.
- Encapsulation
A domain service can access data and functionality it does not own through other service contracts only.
- Stability
Service contracts must be long-lived with a predictable lifecycle.
- Reusable
Services must be developed to be reusable across multiple contexts and by multiple consumers.
- Contract-Based
Functionality and data must only be exposed through standardized service contracts.
- Consistency
Services must follow a common set of rules, interaction styles, vocabulary and shared types.
- Ease-of-Use
Services must be easy to use and composable by consumers.
- Externalizable
Services must be designed so that the functionality these provide is easily externalizable.
API Schema
We decided on REST/JSON as the primary interface standard. Next, we wanted all service developers to use a consistent schema format to document their APIs so that we could leverage seamless discovery, machine interpretation, and common tooling and infrastructure. When we started, we adopted Google Discovery Document (GDD) as the schema format for API specifications. There was not much of community support and adoption for this standard, and we ended up developing significant amount of tooling and support for GDD.
However, in late 2015, as the industry started to throw its weight behind Open API Specification (known then as Swagger), PayPal joined the movement and became one of the founding members of the Open API Initiative, an open-source project under the Linux Foundation. This year we began migrating our API schemas to OpenAPI, and are seeing early dividends in terms of reduced infrastructure investment, better stability and happier developers.
API Style Guide
We have developed a comprehensive API style guide to help ensure consistency across the product teams that contribute to the design and development of PayPal’s REST APIs. The style guide includes aspects such as:
- URI structure
- header usage
- status codes
- resource naming
- query parameters
- schema and types
- request and response representations
- error handling
- versioning
- deprecation
- security
- hypermedia
- API design patterns and use-cases
An initial version of this style guide was open sourced in April 2015. The API style guide and the design patterns therein have evolved a lot since. Today, we announce the general availability of the latest API style guide.
Download the API Style Guide from PayPal’s public GitHub.
We hope this style guide will help you scale your API journey faster.
Author: Nikhil Kolekar
About the author: Nikhil Kolekar is a founding member of PayPal’s API Platform team and is passionate about the disruptive innovation that digital transformation initiatives are bringing to the contemporary world. He and his team are working hard to make seamless inter-networked commerce a reality.
