Exemples des meilleures API Web SOAP/REST/RPC ? Et pourquoi les aimez-vous ? Et qu'est-ce qui ne va pas avec elles ?

Question

Dans mon entreprise, nous commençons à nous intéresser aux API Web pour accéder à nos données et les mettre à jour, dans un premier temps pour les partenaires, puis probablement pour le public à l'avenir. Pour l'instant, la forme que prendra l'API (par exemple SOAP, REST, RPC) est totalement ouverte et nous n'avons encore pris aucune décision. Je suis donc intéressé par les exemples d'API Web que les gens considèrent comme bonnes et par les raisons qui vous poussent à penser ainsi.

Ce qui m'intéresse, c'est de connaître l'avis de personnes utilisant différents langages (nous sommes susceptibles de proposer l'API à des personnes utilisant un certain nombre de plates-formes, notamment .NET, Java, ActionScript et JavaScript) sur les API Web que vous considérez comme de bons exemples et avec lesquelles vous avez eu de bonnes expériences.

Quelques points que j'aimerais aborder :

1. Préférez-vous les services de type SOAP ou ceux de type REST/RPC ? Je pense que les personnes disposant d'un support de plate-forme (par exemple, .NET, Java) préféreront les services SOAP et que les personnes utilisant des langages sans support de plate-forme préféreront les autres, mais j'aimerais valider cette hypothèse.

2. Vous souciez-vous de savoir si une API est réellement RESTful ou s'il s'agit d'un simple GET/POST HTTP de type RPC ? Si oui, pourquoi vous en préoccupez-vous ? Est-il plus important qu'une API se décrive correctement (par exemple, ne prétendez pas être RESTful si elle est de type RPC) que de savoir si elle est réellement l'une des deux ?

3. Nous devons vérifier qui utilise le service. J'ai étudié l'authentification Amazon S3 qui utilise un identifiant public et un jeton privé qui est utilisé pour hacher les paramètres de la requête dans un jeton de vérification (ceci est également similaire à flickr). Avez-vous déjà utilisé ce type d'authentification et comment s'est-elle déroulée ? Y a-t-il des algorithmes de hachage que vous trouvez problématiques (c'est-à-dire non pris en charge par votre plateforme) ? Préférez-vous envoyer le hachage dans un en-tête HTTP ou dans l'URI ?

4. Comment gérer les versions ? Est-ce une bonne idée d'avoir un /v1/ afin que les versions futures puissent être ajoutées en parallèle, ou bien feriez-vous quelque chose de différent, comme indiquer la version dans les données utiles de la demande ou dans la requête ? Pendant combien de temps pensez-vous que la version d'une API que vous avez construite sera prise en charge (par exemple, si la version 2 était introduite, quelle serait votre attente concernant la durée de vie de la version 1) ?

Toute autre opinion et tout autre point à couvrir seraient également utiles.

Je reste délibérément vague sur le type d'API que nous mettons en œuvre, car je cherche à obtenir des conseils généraux sur ce que les gens considèrent comme de bonnes API et de bons mécanismes de mise en œuvre, afin que cet article et ses réponses soient utiles à davantage de personnes à l'avenir.

---

Note : J'ai cherché et je n'ai pas trouvé de question générique à ce sujet - elles semblent toutes spécifiques à un certain type d'API - mais si c'est un doublon, merci de me le faire savoir. De plus, si la question doit être considérée comme un wiki communautaire (je pense que les gens doivent être crédités pour les réponses, donc je n'en ai pas fait un), veuillez me le faire savoir et je la modifierai.

Answer 1

Voici mon point de vue.

1. Bien que venant d'un point de vue Java, je préfère en fait REST. L'enveloppe SOAP avec ses multiples espaces de noms et sa structure complexe est une abomination. Elle tente de résoudre des problèmes pour la plupart imaginaires, et ne résout rien de manière efficace. La seule chose que j'ai trouvé utile dans SOAP, c'est qu'il y a des normes pour l'autorisation et les erreurs. D'un autre côté, ces deux problèmes pourraient être résolus beaucoup plus facilement en incluant quatre attributs standard dans l'élément XML Root - nom d'utilisateur, mot de passe, errorCode, errorDescription.

2. Une bonne description et documentation de l'API est en effet tout ce qui compte. La différence entre REST et SOAP dans un cadre mature réside principalement dans quelques lignes de configuration.

3. Pour SOAP, envoyer le hachage dans le cadre de la sécurité SOAP ; pour REST, j'aime tout regrouper dans les données utiles et éviter les en-têtes HTTP pour l'authentification. Je n'ai cependant que des raisons subjectives, puisque j'ai dû me battre avec des frameworks qui n'exposent pas facilement les en-têtes HTTP.

4. Ma préférence personnelle est d'avoir des URIs différents pour les différentes versions du protocole. D'après mon expérience, cela vous donne plus de flexibilité dans les nouvelles versions, et les anciens clients qui se connectent à des versions non prises en charge d'un protocole cessent de fonctionner immédiatement et pour des raisons évidentes. De plus, il est parfois possible de faire correspondre l'ancienne version de l'application à l'ancien URI, afin d'éviter d'avoir un code de support hérité dans la nouvelle version du serveur.

   Quant à savoir combien de temps vous supportez une ancienne version du protocole... idéalement, tant que vous avez des clients qui l'utilisent. C'est une décision plus commerciale que technique. Vous devriez supporter au moins une version antérieure du protocole. Il est généralement dans votre intérêt de pousser les clients vers la nouvelle version pour réduire les coûts de support hérités ; du côté des clients, la nouvelle version devrait signifier de nouvelles fonctionnalités, un meilleur protocole, et une sorte d'incitation commerciale supplémentaire (si les nouvelles fonctionnalités seules ne suffisent pas).

Answer 2

Vous pourriez être intéressé par la présentation de Joshua Bloch intitulée "How to Design a Good API and Why it Matters". Joshua Bloch est l'auteur de "Effective Java" et est ingénieur logiciel principal et architecte Java en chef chez Google.

Résumé : http://portal.acm.org/citation.cfm?id=1176622

Diapositives : http://lcsd05.cs.tamu.edu/slides/keynote.pdf

Vidéo : http://www.youtube.com/watch?v=aAb7hSCtvGw

Answer 3

Le versionnage pour REST à l'aide des en-têtes Content-Type est bien couvert ici : http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Answer 4

L'approche RPC est également une bonne option. Elle réduit les frais généraux, et des projets comme Ice, Google Protocol Buffers et Apache Thrift facilitent le développement de services basés sur RPC.

Si vous n'avez pas à fournir une API basée sur le Web, le RPC peut également être un choix à explorer.

Answer 5

Je verrais bien ce que fait Amazon - http://aws.amazon.com/ - Les types qui gagnent de l'argent avec ces trucs auront évidemment appris plus de leçons que n'importe qui d'autre.

D'autres API que je regarderais - salesforce.com et l'api CRM de Microsofts étaient plutôt intéressants. Twitter a également une api REST renforcée.