Blog // Exirel.me

Retrouvez tous les articles liés au tag API via le flux rss dédié à ce tag.

HTTP Accept header

Par Florian Strzelecki - 21:45 - 25.04.2014

Tags : Web, HTTP, Hypermedia, Développement, HATEOAS, REST, Technique, Programmation, Bonne pratique, API

La RFC 2616 de l'IETF est une spécification du protocole HTTP/1.1. Ce document décrit notamment les headers des requêtes HTTP à disposition des clients, et en particulier le header "Accept", qui sera le sujet de cet article.

À quoi sert-il ?

En résumé : il permet la négociation de contenu dirigée par le client.

En utilisant Accept, le client indique au serveur HTTP quels types de contenus il est capable de gérer, éventuellement avec un ordre de préférence. Le serveur est alors invité à fournir le type de contenu le plus adapté pour répondre à la demande du client (mais ce n'est pas obligatoire).

Ce paramètre peut être utilisé avec d'autres headers, comme Accept-Language ou Accept-Encoding ; par exemple, le serveur Apache (qui documente sa méthode de négociation de contenu) utilise plusieurs headers pour déterminer la meilleure réponse possible.

Comment ça marche ?

Prenons un exemple avec une requête envoyée par Firefox (28.0), qui utilise ce header par défaut :

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Ceci indique au serveur que le client attend, par ordre de préférence :

Pour le cas d'une balise img, le header sera différent, et contiendra plutôt image/png (j'ai d'ailleurs remarqué que l'URL n'est absolument pas prise en compte par le navigateur pour générer son header).

Les versions et les API (partie 2)

Par Florian Strzelecki - 17:23 - 16.01.2014

Tags : Web, Bonne pratique, Technique, API, Version, HTTP, Hypermedia

Si vous ne l'avez pas déjà fait, je vous invite à lire la partie 1, qui parle d'applications installées plusieurs fois, dans des environnements clients spécifiques à chacun, et où, finalement, le numéro de version dans l'URL n'a pas beaucoup de sens.

Sommaire

  1. Partie 1 : L'application fournie un service via une interface (ou plusieurs)
  2. Partie 2 : Le service est fourni par une (ou plusieurs) applications

Le service est fourni par une (ou plusieurs) applications

Dans la partie 1 donc, j'ai présenté un exemple de SIGB, qu'il faut installer dans un environnement client. Cette fois, je vais prendre le même SIGB, mais avec un seul serveur centralisé : vous êtes alors en position de fournisseur de service, comme peut l'être Facebook, Twitter, Google, et bien d'autres.

Dans ce contexte, il existe des différences fondamentales avec le contexte précédent :

  1. Chaque version de l'application n'est installée qu'une seule fois (par vous)
  2. Les mises à jour sont indépendantes de la volonté des clients
  3. Chaque client décide à quel moment il exploite un changement rétro-compatible
  4. Chaque changement non rétro-compatible impose une adaptation du client (immédiate ou différée)

Les contraintes et les attentes n'étant pas les mêmes, la notion de version peut être traitée différemment.

Les versions et les API (partie 1)

Par Florian Strzelecki - 00:00 - 16.01.2014

Tags : Programmation, Bonne pratique, Technique, API, Version

Vaste sujet que la gestion des versions dans le domaine des API, et cette fois encore ce billet fait suite à une discussion que j'ai eu sur Twitter. Tout a commencé par un tweet d'@edasfr (compte protégé), dont vous pouvez trouver le blog dont je conseille la lecture à cette adresse : n.survol.fr.

Comme les tweets ne suffisent pas, voici un billet qui, je l'espère, vous éclairera sur la gestion des versions et des URLs pour vos (futures) API.

Je ne prétends ni avoir la réponse, ni détenir de vérité absolue : par mon partage d'expérience j'espère seulement vous donner les bonnes informations pour que vous répondiez vous-même à la question.

Sommaire

  1. Partie 1 : L'application fournie un service via une interface (ou plusieurs)
  2. Partie 2 : Le service est fourni par une (ou plusieurs) applications

Mais de quoi est-il question ?

Une API, ce n'est jamais qu'une interface, et dans notre cas, une interface passant par HTTP et ses bonnes vieilles méthodes (GET, POST, PUT, etc.). De facto, il peut exister moins, autant, ou plus d'interfaces que d'applications.

Mais de quelles applications parlons-nous ? C'est là, à mon avis, que se trouve le premier élément de réponse. Vous ne pouvez pas aborder le problème des versions sans savoir dans quel contexte vous vous situez.

Ensuite, qu'est-ce qui est versionné ? Il y a l'application, l'interface, les formats de données, et les données elle-même.

Si vous croisez les types d'applications avec les types de versions, cela donne un large panel de cas à traiter, ce qui n'est pas une mince affaire. J'ai remarqué que la tentation est forte de résoudre un problème par la mauvaise solution, en se trompant simplement sur "qu'est-ce qui doit être versionné", et "de quoi dépendent les versions".

Dans cette première partie, j'aborde le cas d'une application versionnée et distribuée à des clients qui installent chacun leur propre instance, et peuvent utiliser chacun une version différente.

Pour qui sont les API ?

Par Florian Strzelecki - 23:51 - 19.12.2012

Tags : Web, Programmation, Bonne pratique, Technique, API

Bonne question n'est-ce pas ?

Normalement, vous avez deux réactions possibles si vous n'êtes pas développeur :

Oui, mais non. Enfin "presque". C'est compliqué.

Je m'amuse souvent à me décrire comme un #apidealer, parce que c'est un domaine qui me passionne. À dire vrai, le concept de deux machines pouvant communiquer, s'échanger des informations, et ce, sans la moindre intervention humaine pour ça, j'ai toujours trouvé cela magique, et c'est toujours ce que j'ai voulu faire.

Ce qui m'amène à mon premier point : une API, c'est fait pour des machines. Ce sont des machines qui vont appeler l'API, qui vont prononcer les doux verbes HTTP servant à récupérer les données, à envoyer des commandes, à demander des traitements.

En gros, pas besoin de parler comme avec les humains. Pas non plus besoin de parler comme avec un navigateur, parce que - c'est peut-être une révélation pour vous - mais le navigateur, c'est vraiment très limité pour appeler une API (sans extension/plug-in/greffon, je veux dire).

Si nous faisons des API, c'est pour permettre d'écrire des applications qui pourront comprendre les données que nous voulons les voir traiter.

Ce qui m'amène à mon second point : une API sert aux développeurs. Ce sont là les premiers usagers des API. Déjà, parce que ce n'est pas sexy comme un beau site web ou comme une jolie petite application sur son smartphone. Moi je trouve ça sexy as hell, mais je pratique le #datalove alors bon ça compte pas. Ensuite, parce que sans le travail du développeur, l'API ne sert à rien.

Une API doit être facile d'accès pour le développeur. Faire ressortir le meilleur de lui-même et de ses capacités. En échange, le développeur doit prendre soin de l'API, la mettre en valeur, ne pas la sur-exploiter pour rien. Bref, une histoire d'amour - mais seulement entre l'API et un développeur.

Il ne reste plus qu'au développeur d'être responsable, et de fournir de bons et loyaux services aux usagers finaux des données. Oui, des données, pas de l'API. Nuance.

Pourtant, ce soir j'ai entendu à peu près cette rengaine de la part d'un homme qui, par ailleurs, a un réel soucis pour ses usagers (ce que je respecte profondément et sincèrement) :

"Pour modifier l'API il faut que ça serve aux usagers.".

Et par usagers, il entendait les usagers du service qui génère les données (ici, un réseau de transport en commun - ce qui fait un paquet de données). Il entendait les usagers finaux, les gens comme vous et moi qui utilisons un service tous les jours, de manière très concrète, dans le monde physique. Tiens, rien que ce matin j'ai pris le métro, puis le bus, et pour rentrer ce midi pareil.

Oui, mais non. L'API n'est pas faite pour les usagers. Elle permet à des développeurs de proposer des services aux usagers. C'est là la grande nuance.

Si vous ne voulez pas faciliter le travail des développeurs, alors ne fournissez pas d'API. Mais ne délivrez pas une API pour vos usagers. Ce ne sont pas les cibles d'une API. Donnez des outils aux développeurs, et eux feront les outils pour les usagers. Ou alors, faites de vrai outils pour les usagers - et les API ne sont pas des outils pour les usagers.

Une API, c'est une nouvelle histoire d'amour entre un développeur, et une machine.