O Paypal criou sua plataforma como serviços conectados a outros serviços via APIs Restful. Eles desenvolveram diretrizes e padrões de design para a criação e uso dessas APIs, e tornaram o conteúdo público para que outras pessoas usem como inspiração para seus próprios projetos.
O Paypal apresentou diretrizes de design de API desenvolvido durante anos de desenvolvimentos e evolução das APIs que compõem sua plataforma. O guia tem os seguintes princípios como sua base:
- Livre de acoplamento - Serviços e consumidores precisam estar completamente desacoplados entre si.
- Encapsulamento - Um serviço de domínio pode acessar dados e funcionalidades que não possui através de um outro contrato de serviço.
- Estabilidade - Contratos de serviços precisam ser estáveis.
- Reusabilidade - Serviços precisam ser desenvolvidos para ser reutilizados em múltiplos contextos e por muitos consumidores.
- Baseado em contratos - Funcionalidade e dados só podem ser expostos via contratos de serviços padronizados.
- Consistência - Serviços precisam seguir um conjunto de regras comuns, estilos de interação, vocabulário e tipos compartilhados.
- Fácil de usar - Serviços precisam ser fáceis de usar e compor em consumidores (e aplicações).
- Externalidade - O serviço precisa ser desenhado para que a funcionalidade que ele provê seja facilmente externalizada.
Capacidades de negócio são expostas como recursos: toda informação pode ter um nome. O recurso somente pode ser obtido por um único serviço, evitando duplicação. Operações de CRUD são permitidas em recursos, implementadas pelos seguintes verbos HTTP:
- GET - Usado para obter um recurso.
- POST - Usado para criar um recurso ou para executar uma operação complexa em um recurso.
- PUT - Usado para atualizar um recurso.
- DELETE - Usado para deletar um recurso.
- PATCH - Usado para realizar uma atualização parcial em um recurso.
As requisições e respostas HTTP transmitem dados usando JSON Formato de Troca de Dados baseado em um JSON Schema. JSON primitivo - texto, número, lista, vetores, nulo - e tipos comuns são ambos suportados. A versão mais recente inclui endereço, dinheiro, data, tempo, país, número telefônico e outros.
O guia de API inclue casos de uso HATEOS com exemplos de códigos exemplificando como usar hiperlinks seguindo a metodologia REST. Também existem guias sobre o uso de cabeçalhos HTTP (padrão e personalizado) e códigos de status, incluindo um mapeamento entre métodos HTTP e códigos de status, convenções de nomes para URIs, parâmetros de query, recursos, tratamento de erro, versionamento e recursos que serão deprecados. O Paypal também tornou publico outro documento, Design de padrões de API e Casos de Uso, com padrões e exemplos de códigos para o uso de APIs.