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.

Mémento Sites Web – Les bonnes pratiques – v3

Rappels

Les bonnes pratiques Opquast

Les bonnes pratiques de la qualité web (Opquast checklist) sont un référentiel de critères de qualité pour les pages et applications web.

Cette liste est gérée sous le projet Opquast (pour « Open Quality Standards ») mais construite par une communauté de contributeurs.

Une bonne pratique est retenue parce qu’elle fait consensus et uniquement si elle répond aux exigences suivantes :

  • vérifiable par n’importe quel utilisateur
  • internationale
  • réaliste
  • apportant une valeur ajoutée

Le mémento des bonnes pratiques

La liste des bonnes pratiques Opquast a fait l’objet d’un mémento Eyrolles :  Sites web – Les bonnes pratiques.

Ce mémento est un fascicule dépliant, plastifié qui permet de consulter rapidement et facilement la liste des bonnes pratiques.

Mémento v.3 / Bonnes pratiques Opquast v.2 ?

Bonnes pratiques v.1

La première version des bonnes pratiques date de septembre 2004 et un premier mémento a été édité pour l’occasion.

Néanmoins, pour des raisons de lisibilité principalement, une deuxième version du mémento a été produite en janvier 2009 toujours sur la base de la première version des Bonnes pratiques.

Bonnes pratiques v.2

Au tout début de l’année 2010, le projet Opquast a lancé un appel à contributeurs afin de revoir entièrement la liste des bonnes pratiques et de l’actualiser, au besoin.

En février 2010, une nouvelle liste de 217 critères a été validée. Cette nouvelle version du référentiel a fait l’objet d’une nouvelle version du mémento, la 3ème donc.

En savoir plus sur l’atelier Opquast (bonnes pratiques v2)

Les mémento des bonnes pratiques v.3

Le mémento Sites web – Les bonnes pratiques est donc basé sur le référentiel 2010.

Sur 18 pages, ce dépliant contient toujours :

  • une rapide présentation de la qualité web
  • un mode d’emploi
  • la liste des bonnes pratiques classées par catégories
  • les dix principes de la qualité web

Mais cette version s’agrémente également :

  • d’un petit guide de mise en œuvre des bonnes pratiques
  • de la liste des critères classés par profil (design, intégration, éditorial, référencement)

Cette nouvelle édition du mémento des bonnes pratiques offre donc bien plus que quelques ajustement éditoriaux et esthétiques.

Mémento des bonnes pratiques Opquast ouvert sur les pages "par profil métier"
Mémento des bonnes pratiques Opquast ouvert sur les pages "par profil métier"

Acheter le mémento chez Eyrolles
Acheter le mémento chez Amazon

Le projet Opquast

Audit de qualité – Pistes d’analyse

J’ai eu la chance de tester la nouvelle version du référentiel Opquast à titre professperso… non, à titre professionnel (avec Opquast, je ne sais jamais si je le fais pour le boulot ou pour le plaisir !)

img03

Bon, déjà, 217 bonnes pratiques à tester à la main (les tests automatiques n’étaient pas encore prêts), avec la bonne méthode (1), ben finalement, ça se fait.

Une fois que c’est fini, on a un résultat ; un pourcentage de conformité.

Ce qui me semble important – en dehors d’un état d’avancement et de marge de progression – c’est l’analyse que l’on peut en tirer.

En effet, plus que le résultat global, j’ai axé mon analyse sur :

  • les résultats par niveau
  • les résultats par « typologie » de critères

L’analyse par niveau

Constater que les résultats sont meilleurs sur les BP (Bonnes Pratiques) de niveau 1 démontre que les équipes web ont le bon esprit. Elles ne se perdent pas dans les détails et le peaufiné sans avoir traité les points importants en priorité.

Un taux de conformité globale à… disons 60% mais avec 30% de conformité en niveau 1 pour 80% de conformité en niveau 3 signifierait une mauvaises gestion des priorités et peut-être même une méconnaissance du média ! Rien que ça.

par-niveaux2

L’analyse par typologie de critères

Opquast a eu la bonne idée de classer les BP par groupes thématiques.

Avant d’analyser les résultats de mon audit, je me suis posé la question :

  • des objectifs du site,
  • et de la fréquence d’utilisation de certains éléments (ex. : tableaux, Flash) et de l’importance de l’information contenue

A l’aide de ces deux éléments, de manière naturelle, des typologies de critères se sont détachées comme étant plus stratégiques que d’autres.

Ce sont donc sur ces groupes que s’est focalisée mon attention.

En plus de l’analyse en détail, constater que la conformité globale des typologies stratégiques est plus élevée que celle des typologies mineures démontre encore que les équipes web suivent un axe logique par rapport à leurs buts.

radar

Analyse en détail

Et bien sûr, une analyse d’un audit de qualité web n’est pas, certainement pas, une suite de pourcentages et de graphiques (aussi jolis soient-ils).

Une fois qu’on s’est focalisé sur un groupe de BP, on regarde en détail les points de non-conformité.

  • Est-ce que ces points concernent tous une même étape (compétence, planning, outil) ?
  • Est-ce qu’ils sont modifiables facilement ?
  • Est-ce qu’ils font partie d’un choix stratégiques et n’ont pas à être modifiés ?

On se pose le même type de question sur les points de conformité et on se rend compte qu’on en tire rapidement des conclusions sur les axes forts et les axes faibles d’un site, d’une méthode, d’une équipe, etc.

À vos analyses !

coche

(1) Il y a, si on veut, des formations pour ça chez ces messieurs de Temesis.

Des sites web de qualité grâce à …vous !

Opquast - Open Quality Standarts

Quand j’ai commencé à m’intéresser à ce qu’on va appeler le web de qualité (standards, accessibilité, expérience utilisateur, etc.), j’ai eu la chance de rencontrer les bonnes personnes qui m’ont donné les bonnes références. (Ne partez pas ! ce billet ne va pas parler que de mon nombril !)

Autre que les liens vers les spécifications du W3C (imbuvables pour une débutante !), on m’a bien sûr indiqué des sites tels que OpenWeb ou Pompage.

C’est à cette même époque (2005 ?) que l’on m’a fait découvrir le projet Opquast.

Opquast était merveilleux pour la débutante que j’étais car il liste des bonnes pratiques toutes pleines de sens. Je découvrais à la même époque que ce n’était pas un hasard si chacune de ces bonnes pratiques étaient intelligente : elles avaient été conçues selon des critères exigeants et en collaboration (en groupe, on réfléchit mieux que tout seul, ben oui).

Cette liste de bonnes pratiques a été rapidement accompagnée d’un outil pratique de mise en œuvre : Mon Opquast.
Non seulement j’avais cette liste à disposition, des explications de l’utilité de ces bonnes pratiques, mais en plus, j’avais une interface simple pour suivre l’application (ou non) de ces préconisations.

Depuis, je suis devenue une grande (si, si) et Mon Opquast est toujours aussi utile pour moi. Il l’est également au sein de mon entreprise car il permet un suivi simple et partagé de la qualité de tout un parc de site.

Le web évolue, comme chacun sait, rapidement. Et la liste des bonnes pratiques est en train d’être revue. Ce que ça donne ? 235 bonnes pratiques candidates au moment où j’écris ces lignes, plus des propositions, plus des refusées… le tout proposé à votre sagacité. Oui, la votre. Car après une élaboration en comité restreint (à laquelle j’ai eu le bonheur de participer), les bonnes pratiques sont soumises aux commentaires de tous.

Participer à ce genre d’initiative est particulièrement enrichissant. Cela permet d’avoir sous les yeux un condensé à la fois des habitudes de professionnels obsédés intéressés par la qualité, des désaccords argumentés entre ces créateurs de sites web, de se soumettre soi-même à une méthode constructive et exigeante, le tout au service de la qualité des sites web. Bref, que du bonheur.

Comme à chaque fois que je suis enthousiaste, j’ai l’impression d’être confuse. Si je devais résumer en une phrase : « Vous faites des sites web et vous aimez le faire bien ? Participez à l’appel à commentaire de Opquast V2 » :

…Et si je m’étais faite payée à chaque fois que j’avais fais de la « pub » pour Opquast, je serais riche et Opquast serait sur la paille ! 😀

Le Mémento des bonnes pratiques, v.2

Sites web - Les bonnes pratiques
Sites web - Les bonnes pratiques

Je me suis retenue d’appeler ce billet d’un intriguant « Je l’ai ! » parce que bon, c’est bien beau de relayer les bonnes pratiques éditoriales si c’est pour ne pas les respecter soi-même !
Pourtant, c’était certainement ma pensée quand j’ai reçu -gâtée que je suis- un exemplaire du tout nouveau Mémento des bonnes pratiques du web.
Bon, ok, je l’avais quelques peu réclamé… Ben quoi ?! on ne sait jamais !

Toujours est-il que je suis en mesure de vous parler de cette nouvelle version de la liste des bonnes pratiques Opquast.

Les différences d’avec la première version sont essentiellement esthétiques mais le changement est important : les couleurs sont plus contrastées et la lisibilité est meilleure.
Plus doux, plus rose, en un mot, plus sexy ; bref, le Mémento des bonnes pratiques d’Élie Sloïm est plus beau en vrai que sur le web (1).

Les bonnes pratiques n’ont pas changées (ou alors je n’ai pas été assez pointilleuse ?!). Par contre, on notera de petits et de gros changements sur le contenu « didactique » qui accompagne le référentiel.
J’aime particulièrement les « Dix principes pour la qualité web » qui mériteraient à eux tous seuls … tout un livre ! 😉

Et, ce qui n’a pas changé non plus, c’est le prix… 5 €.

Mémento Sites Web – Les bonnes pratiques
Élie Sloïm et les contributeurs Opquast

Éditions Eyrolles
Deuxième édition, Janvier 2009
(1) « Private joke » – partagée par les quelques 300 personnes qui ont assistées à Paris Web 2008 – ayant pour but d’alimenter les moteurs de recherche sur la requête « plus beau en vrai que sur le web »…

Ma petite pêche du 03/11/08

Voici, via Blogmarks, le ou les derniers favoris que j’ai recueillis.

Synchronisation automatique et quotidienne via Blogmarks, outil de gestion de favoris en ligne.