Bonnes pratiques des API – Compte-rendu

Pour les besoin de mon projet Spoiled People (voir Projet de liste cadeaux sur GitHub), je dois monter en compétence côté API. Je suis allé voir du côté de la conférence « Bonnes pratiques des API ».

Cette conférence de 15 petites minutes est un retour d’expérience, y compris sur les ratés.

La première leçon qu’Éric Daspet a appris et nous transmet concerne la littérature et la pratique. Sans critiquer la littérature, son constat a été que d’un point de vue pragmatique, il vaut mieux s’adapter aux envies des utilisateurs (les développeurs).

Eric Daspet - Paris Web 2013 - Photo Brice Favre

Les recettes à suivre

Voici une première liste de conseils issus de cette conférence.

Internationalisation

  • Toujours mettre des heures et non juste une date
    Pas GMT mais en mettant un fuseau horaire que vous allez interpréter dans chaque paramètre)
    Voir le commentaire d’Éric ci-dessous.
  • Attention aux langues : anticiper la possibilité d’avoir plusieurs langues, utiliser UTF-8 (et non de l’ISO).

Pagination

  • L’offset sont de fausses bonnes idées.
  • Trier les données par ordre (alphabétique, de date, d’arrivée,…) et utiliser « after | before » (plus ancien ou plus récent que tel item)
  • Rendre la pagination obligatoire.
  • Mettre des limites de taille avec une profondeur maximum

Un bon exemple : Twitter

Versionnement

Même si dans la littérature, le versionnement peut être vu comme une mauvaise pratique, en l’état, nous ne sommes pas forcément prêt à nous en passer. Partir du principe qu’on va se planter et, alors, qu’on fera une V2 plutôt que mettre des bouts de sparadrap.

  • Prévoir un /v1 en bout d’URL dès le début

(NB : Le versionning dans les en-têtes n’est pas assez simple et ne sera pas pratique pour vos utilisateurs et donc ne servira pas)

Sécurité

  • HTTP Basic Oauth
  • + SSL
  • imposer HTTPS
  • Ne pas permettre le SSL désactivé dans le SDK (qui est recommandé)
  • Clé d’API : savoir à tout moment qui fait la requête. Prévoyez-la.

Structure

  • Faites de l’hypermédia mais ça ne suffit pas.
  • Vos adresses doivent être « bidouillables » de façon qu’elles soient prédictives.
  • Une adresse doit ressembler à un nom de fichier : pas de caractères spéciaux encodés, que des minuscules, pas de caractères accentués.
  • Réduire la hiérarchie aux maximum (3 semble être la bonne pratique).

La conclusion

La clé :

  • En faire peu.
  • Ouvrir un maximum de champs pour plus tard.
  • Faire simple.
  • Utiliser les standard existants.
  • Penser pragmatique.
Diaporama de la conférence
NB : Le diaporama contient 10 bonnes pratiques supplémentaires en page 11.

Internet et société : la responsabilité des professionnels

Parmi toutes les conférences que j’ai vues et aimées cette année à Paris Web, certaines m’ont particulièrement marquée par rapport à leur thématique. En effet, il me semble que plus d’une présentation nous renvoyait à notre responsabilité en tant que professionnels et utilisateurs d’Internet.

« La rencontre entre hacktivisme et sociétés civiles, un enjeu pour les libertés numériques » d’Amaëlle Guiton m’a permis de rattraper un retard que je cachais honteusement. Mais pas que ; loin de là.

Nous vivons, avec l’arrivée somme toute récente d’Internet, une nouvelle révolution après celle de l’imprimerie (je n’invente pas cette belle image mais reprends ce que j’ai entendu). Notre capacité à communiquer avec toute la planète et à transmettre est sans limite. Sans limite ? Le politique a bien compris le pouvoir que donne Internet et se pose les questions de ces limites. Mais se pose-t-il les bonnes questions ? Internet n’est pas une question politique. Internet est un support qui équipe la société et la société (civile, mondiale) ne doit pas le laisser lui échapper pour être contrôlé par un pouvoir politique, soit-il capitaliste, anarchiste, socialiste ou tout autre -iste.

Internet est un outil qui équipe la société. Il ne doit pas être récupéré par le mercantile et le politique

Oui, mais Internet, c’est compliqué. Comprendre en quoi la liberté du Net c’est important (cf. « Vers une nouvelle éthique » de Xavier Mouton-Dubosc), ce n’est pas (encore) à la portée de ma mère, mon voisin, mon boucher qui a autre chose à faire. Les enjeux de la liberté individuelle et de la vie privée vont bien plus loin que le « je n’ai rien à cacher » de ma cousine lycéenne et de mon épicier réac’.

Mais nous, professionnels du web, nous sommes bien mieux placés que les politiques pour comprendre notre média et ses possibilités. Nous nous y intéressons, connaissons sa mécanique, sommes consommateurs et acteurs. Il reste encore un rôle que nous pourrions choisir de revêtir : vulgariser et transmettre.

Si nous ne le faisons pas, c’est TF1 qui le fera.

Mais que transmettre ? À mon sens et en m’appuyant sur les conférences qui ont motivé ce billet, je dirais :

  • En quoi Internet est notre – nous, les citoyens du monde – média, fait de nos données ?
  • Comment le monde mercantile utilise et pourrait utiliser Internet (nos données) ?
  • Que souhaite-t-on qu’Internet devienne ? Projetons-nous dans 100 ans.

Dans cette révolution que nous vivons, depuis les premiers rangs pour les professionnels que nous sommes, nos actes et nos non-actes seront la cause de ce que sera Internet demain.

À nous de nous emparer d’Internet avec recul et discernement.

Car Internet est un nouvel eldorado pour notre monde capitaliste. Les possibilités que l’on entrevoit actuellement ne sont sûrement rien par rapport à ce que cela va devenir. Les perspectives que nous donne, par exemple, Avi Itzkovitch dans sa conférence « Designing with Sensors: Creating Adaptive Experiences » sont autant de nouveaux services que nos appareils pourront nous rendre – et je m’enthousiasme autant à cette idée que je me réjouis de mon utilisation actuelle de mon mobile. Mais n’est-ce pas autant de raisons de s’inquiéter de la compromission de la liberté individuelle, de la disparition de la vie privée ? Si certains s’en inquiètent, la réponse pour moi est la même que ci-dessus  : à nous d’être responsable de notre support, de vulgariser pour le « grand public », de réfléchir et de se projeter pour être sûrs de ne pas créer un monstre.

Olivier Thereaux et Karl Dubost nous ont donné des premières pistes de réflexion avec « Esthétique et pratique du Web qui rouille » – à nous de les creuser.

Chaque utilisateur d’Internet doit être vigilant par rapport à ce qu’il met en ligne et à la manière dont il utilise ses applications. Mais c’est à nous – professionnels du web – de relayer ce message de vigilance sans dramatiser mais de vulgariser, donnant à chacun la possibilité de prendre position.

Liens

Ces quatre conférences ont motivé ce billet mais de nombreuses autres ressources vont pouvoir nous aider à cette prise de conscience et à la transmission.
Voici quelques éléments que je peux vous indiquer :

Remerciements

Merci aux orateurs que j’ai cités ci-dessus pour ce partage et merci aux auditeurs qui y ont ajouté leurs questions et leurs points de vue.
Merci à Paris-Web pour ces choix qui n’étaient pas si évidents ; merci vraiment !
Merci à Ekino qui m’a permis d’assister à ces journées de conférences.

Mes autres articles sur Paris Web 2013

De l’enthousiasme post-Paris Web

Cette année, c’était la première fois depuis 2008 que je venais à Paris Web en tant qu’auditrice. Avoir fait partie du staff et redevenir simple « consommateur » est une délectation (mais chut ! il ne faut pas que les staffeurs le sachent : je ne voudrais pas qu’ils aient envie de quitter l’équipe, ils sont trop bons).

En étant qu’auditrice, j’ai pu profiter des conférences et je me suis réjouie des choix faits pour le programme. J’ai particulièrement apprécié qu’il y ait des conférences nous faisant prendre du recul sur nos métiers et notre support.

J’ai également pu, enfin !, discuter aux pauses et profiter des gens. Je n’ai pas échangé longuement mais j’ai pu saluer plein de monde et discuter avec des gens que je ne connaissais pas – ce qui est aussi le but de tels événements. J’ai eu des retours intéressants sur ma conférence – auditeurs, vraiment, allez parler aux orateurs aux pauses, ils ne demandent que ça !

Photo Nazcange – CC by-NC-SA

Je reviens de Paris Web pleine de cette belle énergie que les gens s’insufflent les uns aux autres quand ils se réjouissent d’être là. Je reviens de Paris Web avec le constat, encore une fois, que nous aimons notre métier et, plus encore, que nous voulons le faire bien, même quand il faut se battre pas-à-pas pendant des années pour ce bien. Je reviens de Paris Web avec une prise de conscience toute personnelle ; je me sens plus mature et mieux préparée à transmettre. Je reviens de Paris Web avec le sentiment d’avoir reçu un cadeau et d’être plus riche, maintenant, de le transmettre.

Photo Nazcange – CC by-NC-SA

Je lis de-ça, de-là, des retours difficiles post-Paris Web. Pour avoir fait partie du staff je sais comme le retour peut être difficile. J’ai déjà eu des « baby blues » à couper au couteau. C’est douloureux et ingérable. Cette année, le staff a en plus dû gérer un nouveau lieu (et quel lieux !) avec son lot de difficultés. Une centaine d’auditeurs en plus que les autres années (une centaine d’heureux en plus ! merci le staff).
Bien heureusement, certains, je le sais, n’ont pas du tout été raisonnables ; c’est tant mieux. Et si leur Paris Web blues est accentué par ce manque de sommeil, réjouissez-vous : vous devez votre état au plaisir que vous avez su prendre et à l’investissement que vous avez su mettre. Et pis bon, je le sais très bien que si c’était à refaire vous le referiez.

Photo frphoto1 – CC by-SA

Alors oui, le retour au quotidien est souvent difficile – pour tous ; viennent parfois se greffer de mauvaises nouvelles dont on se serait bien passées, mais réjouissons-nous, tous : si certains sont dans un triste état, c’est du trop plein qu’ils ont reçus. Transmettez ce trop plein. Qu’il soit de connaissances, de tendresse, d’énergie, du plaisir de donner, etc.

Savourons le plaisir de ces deux ou trois jours en mettant en application, en testant, en transmettant. Faisons durer cette belle énergie reçue.

Photo frphoto1 – CC BY-SA

Mes conférences chouchous à Paris Web 2013

NB : Retrouvez toutes ces conférences – résumé, diaporama et vidéos dès que disponibles – dans le programme de Paris Web 2013.

La folle journée, ou les fourberies d’un projet

Par Julien Dubedout, Florian Boudot et Christophe Andrieu

Vous allez me dire : « Comme tout le monde ! ».
Cette conférence n’était pas seulement une réussite parce qu’elle était très drôle. C’est avant tout une excellente conférence parce qu’en même temps d’être caricaturale, elle était très juste.

Elle faisait autant de mal que de bien ; une très bonne catharsis.

Je code donc je teste…

Par Cyril Balit

Sûrement parce qu’on touche au domaine de la qualité. Mais aussi parce que Cyril sait remettre les choses à leur place et montrer que faire bien peut être pris en compte simplement.

Théorie du flow et webdocumentaires

Par Florent Maurin

J’ai découvert cet état de flow et ai trouvé ça très intéressant. Si Florent Maurin nous le présentait ça dans un contexte « stratégique » pour inciter à la lecture de webdocumentaires, je me suis promis de garder ça en tête aussi pour le développement personnel, la formation et la documentation (« If you want them to RTFM, make a good FM! »)

La rencontre entre hacktivisme et sociétés civiles, un enjeu pour les libertés numériques

Par Amaëlle Guiton

Un énorme coup de cœur ! Merci à Paris-Web d’avoir retenu ce sujet pour son programme !

Amaëlle nous a présenté une étude richement documentée qui nous donne toutes les billes nécessaires pour expliquer l’hacktivisme à ma grand-mère (ça va la passionner !).

…Ok, j’avoue, c’est à moi d’abord que ça va servir ! j’ai des choses à rattraper sur ce sujet.

(J’en reparle dans Internet et société : la responsabilité des professionnels)

Un bon design n’est pas beau !

Par Sébastien Desbenoit

D’abord, pour les qualités d’orateur de Sébastien (Sébastien ne présente pas une conférence, il présente un spectacle (sérieux, certes) ; c’est autant de travail en plus pour lui, autant de plaisir et de fluidité de notre côté.)

Mais également pour l’angle pris par un designer sur comment il faut appréhender le beau dans le design. Et pour la remise en question. (Feinte ? Je suis sûre qu’il le savait déjà depuis bien longtemps 😉 !)

Vers une nouvelle éthique

Par Xavier Mouton-Dubosc

Tout comme pour la conférence d’Amaëlle, je suis ravie de voir à Paris Web une conférence nous parlant de notre responsabilité face à nos contemporains au sujet de notre média. Je suis loin de faire figure de bonne élève : je ne saurais rien expliquer à un tiers, je suis loin de maîtriser le sujet mais je prends de plus en plus conscience que je dois être parfaitement renseignée et expliquer, vulgariser, partager. Merci Xavier de ce rappel à l’ordre 🙂

(J’en reparle dans Internet et société : la responsabilité des professionnels)

Keep calm and carry on

Par Lou Schwartz

J’ai forcément été séduite par le côté humain de cette conférence. Mais également touchée par l’entêtement de Lou à vouloir aider cette jeune fille (ou sa boite ? être bien, produire bien, tout ça 😛 !)

Enfin et surtout, j’ai adoré les idées mises en place pour permettre à quelqu’un de rendre concrètes des considérations sur sa propre personne alors qu’elle avait du mal à le faire. J’espère que je garderai ça en tête et que, moi aussi, je penserai à l’avenir à utiliser les Lego, les schémas heuristiques et les graphes.

Esthétique et pratique du Web qui rouille

Par Olivier Thereaux et Karl Dubost

Là encore, je crois que j’ai aimé que l’on prenne du recul à propos de notre support et qu’on se pose des questions par rapport à nos responsabilités qui dépassent largement celle de faire un bon site web à un client et ce parce qu’Internet est bien plus qu’un support commercial ! Ne l’oublions pas.

(Je l’évoque dans Internet et société : la responsabilité des professionnels)

Bureau des plaintes des standards

Par Robin Berjon (informelle)

Parce que c’est une excellente idée, je trouve, de la part de Robin. Et également parce que je crois savoir que, malgré une envie partagée des deux côtés – j’en suis sûre, le dialogue entre le W3C et les développeurs manque encore de densité.

Merci Robin. Encore !

Designing with Sensors: Creating Adaptive Experiences

Par Avi Itzkovitch

Parce qu’il ne faut pas oublier, tous responsables et sensibilisés que nous sommes, de continuer à s’enthousiasmer par ce que la technique peut et va pouvoir nous permettre de faire.

N’ayons pas peur des usages : soyons vigilants, pédagogiques et évangélisons !

(J’en reparle dans Internet et société : la responsabilité des professionnels)

Mobile et accessibilité, une partie à Troie

Par Goulven Champenois

Parce que j’ai toujours pensé que le référencement pouvait être un cheval de Troie pour l’accessibilité et que ça m’a fait plaisir de voir cette idée réutilisée – en mieux ! – avec le mobile.

Et parce que c’était très pertinent et que tout ce qui peut servir l’argumentation pour l’accessibilité est à accueillir à bras ouverts !

Le ticket 3057

Par Thomas Zilliox (Lightning Talk)

Parce que c’était très drôle. Parce que c’est une petite partie de l’histoire d’Internet. Parce que c’est symptomatique et représentatif de certains aspects d’Internet. Tiens, un sociologue devrait se saisir du même sujet ! (Il y a un sociologue dans l’assistance ?)

Explorer le système solaire en 4 minutes !

Par David Catuhe (Lightning Talk)

Moi, je voulais que David Catuhe gagne les Lightnings ! …Parce que quand même, il a mis fin au plus vieux débat du monde : on sait enfin, de manière sûre puisque David l’a montrée pas à pas, comment l’univers à été créé. Ce n’est pas rien !

Et puis il a allié technique (comme tous), humour (comme quasiment tous), performance (comme beaucoup) et …poésie (comme aucun autre) ! 😛

Développons notre efficacité !

Par Teddy Marie-Luce

De manière très ironique, je liste dans mes chouchous un atelier auquel je n’ai pas assisté (!) parce que j’en suis sortie au bout de 2 minutes (re !)
Un manque de compréhension de ma part et je suis partie vers un autre atelier qui n’était pas du tout de la vulgarisation comme je l’avais imaginé.

Je me suis rattrapée à une pause en demandant à Teddy de me raconter ce que j’avais raté ; ce qu’il a très gentiment fait.

Et j’ai été fort triste d’avoir raté un atelier autour du développement personnel qui aidait à passer outre une partie de nos difficultés.

Après la macro, la micro !

Par Vincent Valentin

J’aurais bien dit que j’ai aimé cet atelier simplement parce qu’il parlait de typographie (ce qui me suffit). Ou encore en particulier de micro-typographie (qui est un sujet encore plus fun, n’est-ce pas ?)

Mais en plus, il était animé par Vincent Valentin que je soupçonne d’ignorer à quel point il est drôle (oui, parce qu’il y en a marre de lui dire à quel point il est talentueux ! tout le monde lui dit déjà !) ;p

Mes autres billets sur Paris Web 2013 :
Pour ma propre conférence, voir le résumé sur w3qualité.
Merci à Franck Paul pour ses photos (cliquez dessus pour voir les originales).