Paypal vient de mettre à disposition sur son compte GitHub un guide sur le design de ses APIs.

Au delà de l'aspect purement documentaire, ce guide expose de façon simple et clair, bon nombre de bonnes pratiques en terme de design d'API RESTful.

On y trouve des sujets classiques comme :

  • les verbes HTTP et leur utilisation
  • les Statuts HTTP
  • le templating d'URI
  • le versionning
  • le nommage des ressources

Ainsi que des sujets moins connus comme :

  • JSON patch pour définir la mise à jour partielle d'une ressource
  • Les liens hypermédia
  • les opérations complexes (ne pouvant être traitées comme des opérations de type CRUD)
  • les ressources en lecture seul (pour permettre la mise en cache)

En conclusion, voici un guide qui constitue autant une source d'information concernant les principes sur lesquels sont basées les APIs Paypal, qu'une source d'inspiration pour tous les designers d'API.