Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News PayPal’s API Style Guide and Patterns

PayPal’s API Style Guide and Patterns

Leia em Português

This item in japanese

Lire ce contenu en français


PayPal has created their platform as services connected to each other through RESTful APIs. They have developed guidelines and design patterns for creating and using these APIs, making them publicly available for other developers to get inspiration for their own projects.

PayPal has come up with API design guidelines over years of developing and evolving APIs that serve their platform. The guide has the following principles at its foundation:

  • 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 stable.
  • 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 compose in consumers (and applications).
  • Externalizable – A service must be designed so that the functionality it provides is easily externalizable.

Business capabilities are exposed as resources – any information that can have a name. A resource is to be provided by only one service, avoiding duplication. The CRUD operations are permitted on resources, implemented by the following HTTP verbs:

  • GET - To retrieve a resource.
  • POST - To create a resource, or to execute a complex operation on a resource.
  • PUT - To update a resource.
  • DELETE - To delete a resource.
  • PATCH - To perform a partial update to a resource.

The HTTP requests and responses transmit data using the JSON Data Interchange Format based on a JSON Schema. Both JSON primitive – string, number, enumeration, array, null - and common types are supported. The latter include address, money, date, time, country, phone number, and others.

The API guide includes HATEOAS use cases with codes samples exemplifying how to use hyperlinks following the REST methodology. There are also guidelines on using HTTP Headers (standard and custom) and status codes, including mapping between HTTP methods and status codes, naming conventions for URIs, query parameters, resources, error handling, versioning and deprecation. PayPal has also made public another document, API Design Patterns And Use Cases, with patterns and code samples for using APIs.

Rate this Article