PayPal a créé sa plate-forme en tant que services connectés les uns aux autres via des APIs RESTful. Ils ont élaboré des recommandations et des modèles de conception pour créer et utiliser ces APIs, les rendant publics pour que d'autres développeurs puissent s'en inspirer pour leurs propres projets.
PayPal a élaboré ces recommandations de conception d'APIs au cours des années de développement et de maintenance évolutive des APIs qui servent leur plate-forme. Le guide comporte les principes suivants comme base :
- Couplage faible - Les services et les consommateurs doivent être faiblement couplés les uns aux autres.
- Encapsulation - Un service de domaine peut uniquement accéder aux données et aux fonctionnalités qui ne lui appartiennent pas via d'autres contrats de service.
- Stabilité - Les contrats de service doivent être stables.
- Réutilisabilité - Les services doivent être développés pour être réutilisables dans de multiples contextes et par de multiples consommateurs.
- Basé sur les contrats - La fonctionnalité et les données ne doivent être exposées que via des contrats de services standardisés.
- Consistance - Les services doivent suivre un ensemble commun de règles, de styles d'interaction, de vocabulaire et types partagés.
- Facilité d'utilisation - Les services doivent être faciles à utiliser et à composer par les consommateurs (et les applications).
- Externalisable - Un service doit être conçu de manière à ce que la fonctionnalité qu'il fournit soit facilement externalisable.
Les fonctionnalités métier sont exposées en tant que ressources - toute information pouvant contenir un nom. Une ressource ne doit être fournie que par un seul service, pour éviter les doublons. Les opérations CRUD sont autorisées sur les ressources, implémentées par les verbes HTTP suivants :
GET
- Pour récupérer une ressource.POST
- Pour créer une ressource, ou pour exécuter une opération complexe sur une ressource.PUT
- Pour mettre à jour une ressource.DELETE
- Pour supprimer une ressource.PATCH
- Pour effectuer une mise à jour partielle d'une ressource.
Les requêtes et les réponses HTTP transmettent des données en utilisant le JSON Data Interchange Format basé sur un schéma JSON. Les types JSON primitifs - string, number, enumeration, array, null - et les types communs sont pris en charge. Ce dernier comprend entre autres les adresses, les valeurs monétaires, les dates, les heures, les pays et les numéros de téléphone.
Le guide de l'API comprend des cas d'utilisation de HATEOAS avec des exemples de codes illustrant comment utiliser des hyperliens avec la méthodologie REST. Il existe également des recommandations sur l'utilisation des en-têtes HTTP (standard et personnalisé) et des codes d'état, y compris le mappage entre les méthodes HTTP et les codes d'état, les conventions de nommage pour les URI, les paramètres de requête, les ressources, la gestion des erreurs, les versions et la gestion de la dépréciation. PayPal a également rendu public un autre document, Modèles de Conception d'API et Cas d'Utilisation, avec des modèles et des exemples de code pour l'utilisation d'APIs.