Photo de harold.lloyd depuis Flickr

Pourquoi faire ?

Pourquoi fournir une API ? Si vous lisez cela vous devez déjà avoir une petite idée… Le principe d’Internet c’est le partage, et il existe une multitude de protocoles qui permettent ces échanges (http, ftp, p2p…).
Quel que soit votre activité, son but n’est pas de rester confidentielle, et vous souhaitez sûrement la partager avec le plus grand nombre, le meilleur moyen est de multiplier les manières d’utiliser votre travail.

Que votre webservice fournisse des données (statistiques par exemple) ou des services (calculs, paiement…), il doit trouver son public. En proposant un maximum de possibilités d’y accéder vous augmentez les usages possibles, et surtout vous donnez la possibilité aux utilisateurs de créer des usages auxquels vous n’avez même pas pensé. Votre application devient le vecteur d’usages innovants.

Choisir un format

Les architectures REST ou soap sont très répandues et leur usage est possible simplement via une foule de langages. Vous pouvez rendre votre réponse dans un format défini, mais n’hésitez pas à le rendre paramétrable pour fournir au choix du XML, du JSON ou même du YAML par exemple.
Plus vous proposerez d’options, plus votre API à des chances d’être utilisée ! Vous n’êtes certainement pas le seul à fournir ce genre de service, soyez le meilleur pour garder vos utilisateurs.

Attention à bien penser dès le début aux différentes pistes que vous souhaiter suivre afin de ne pas devoir modifier votre API par la suite et risquer de perdre des clients pour un problème de non compatibilité. Le cas échéant, prévenez les le plus tôt possible et accompagnez les dans la démarche.

Paramétrer

Et tout un tas d’options peuvent êtres ajoutées. Elles peuvent paraitre anodines mais seront d’un grand secours à vos clients. Vous pouvez par exemple leur fournir un compteur d’utilisation de l’API et pourquoi pas un historique des appels. Dans le cadre de prestataires de paiement par exemple, si un callback doit être fait, donnez une liste d’ip publiques afin que le client filtre les appels, donnez lui aussi la possibilité de choisir le nom des variables renvoyées, et pourquoi d’en ajouter… Si les données sont sensibles ajouter une clé secrète et un hashage des données pour certifier les données.

Ne mettez pas n’importe quoi mais restez à l’écoute des demandes, il y a sûrement des cas auxquels vous ne pensez pas, mais qui sont indispensables à vos utilisateurs.

Afin de gérer certaines options, l’accès à un back-office devient nécessaire, ca complique légèrement la tâche mais cela permet de faciliter les échanges avec votre cible. Vous pourrez ainsi collecter un email, attribuer une clé d’API, paramétrer l’API, communiquer avec l’utilisateur, lui fournir des infos statistiques sur son utilisation… Et récolter un maximum d’information pour améliorer votre service.

Sécuriser & tracer

La clé d’API à deux intérêts, limiter l’accès à certaines données ou services à certains clients, et tracer l’utilisation de chacun afin d’en extraire des données statistiques. Ces données vous seront utiles pour améliorer votre service en fonction des usages, mais aussi de mettre en place une stratégie de monétisation.

Une clé secrète permet également d’encoder les données afin de sécuriser les échanges pour qu’ils ne transitent pas en clair et de valider que les données en retour proviennent bien d’un tiers de confiance ayant connaissance de la clé.

Monétiser

Augmenter les usages et favoriser l’utilisation de votre API c’est bien, mais il peut devenir nécessaire de rentabiliser le service ou au moins de payer les frais d’infrastructure (serveur, maintenance, bande passante…). La clé d’API intervient encore ici pour permettre de facturer ou limiter les appels.

On peut imaginer une solution ou les 1000 premiers appels mensuels sont gratuits, au delà un abonnement permet de continuer à utiliser le service.

En plus de la clé d’API pensez à vérifier d’autres éléments comme l’ip pour éviter que des petits malins multiplient les comptes pour contourner le système !

Documenter

Avant d’utiliser un webservice, une phase d’analyse est nécessaire afin de cerner les possibilités et les limites de l’API. Cette phase est importante, c’est le premier contact du développeur avec votre produit. Il doit rapidement cerner si il pourra l’utiliser ou pas. Il en a probablement ciblé plusieurs, et ne les implémentera pas tous. Il faut donc le rassurer au plus vite, la documentation est là pour cela. Elle doit à la fois lui présenter le produit, l’API, des exemples, une FAQ… Tous les éléments dont il pourrait avoir besoin sans chercher à droite à gauche.

Pour commencer, une présentation de l’application, et des possibilités de l’API est indispensable pour dégrossir et permettre au lecteur de cerner le sujet rapidement. Ensuite, les pré-requis à l’utilisation de l’API sont nécessaires, avec pourquoi pas les différentes étapes de l’inscription au service. Le but est de faciliter l’implémentation de l’API, que ce soit pour un simple test ou pour un projet en production.

Donner des exemples

Le bla bla c’est bien, mais un exemple ca aide. Avec la mise en place de l’appel à l’API juste avec la documentation, on peut passer à côté d’une subtilité, surtout si le document n’est pas dans notre langue ou mal traduit.
Un exemple de code permet de tester rapidement et de s’assurer que l’appel fonctionne correctement. Les explications permettent ensuite de d’aller plus loin et de jouer avec les options. Je vous dirais bien de mettre cet exemple en PHP pour sa popularité et sa simplicité, mais identifiez bien votre cible afin de fournir les exemples dans les langages les plus susceptibles d’être utilisés.

Fournir une bibliothèque

Pour faciliter l’usage d’un webservice, certains fournissent directement une bibliothèque. Si l’API est complexe cela permet de manipuler facilement les objets et peut simplifier l’implémentation, à condition de répondre au besoin de l’utilisateur. Dans le cas contraire son encapsulation peut s’avérer fastidieuse. Cela peut aussi permettre de déplacer une partie de la logique métier sur le serveur client.
Certains service bancaires offrent la possibilité de compiler directement une extension PHP avec la clé d’API par exemple . On étend ainsi les possibilité du langage lui même et l’expérience utilisateur est excellente. De plus, la clé d’API ou le mot de passe ne sont plus accessibles directement au développeur. C’est un plus non négligeable pour certaines données sensibles.

Fournir un environnement de tests

C’est parfois nécessaire et souvent indispensable. On doit souvent tester l’utilisation dans des conditions similaires à l’environnement de production mais sans contraintes. Toujours avec l’exemple du paiement, l’utilisation d’un numéro de carte bancaire de test permet de simplifier les tests et de simuler les transactions. En règle générale un paramètre supplémentaire à l’appel de l’API permettra de changer de mode et de tester dans des conditions quasi réelles simple à mettre en oeuvre.

Pour conclure…

Les usages de Webservices sont variés, et ces conseils ne sont pas exhaustifs, votre expérience sûrement différente vous a apporté d’autres enseignements, partagez les avec nous !

Sur le même thème

• Opquast : Sites web, les bonnes pratiques
• Trouver un bon hebergeur web, quels critères ?
• Les générateurs de sprites CSS
• Participons à l’utopie web !
• Optimiser son site web

Je vous propose de découvrir Notepad++. Il ne fonctionne que sous Windows, mais apporte un véritable plus pour cette plateforme dont l’éditeur par défaut est vraiment trop simpliste.

C’est un logiciel gratuit sous licence GPL. Je le trouve idéal car très fonctionnel, simple à installer, rapide à lancer et extensible. Il est donc idéal quand on change souvent de poste et que l’on veut rapidement retrouver ses repères.

Photo de PSD depuis Flickr

Fonctionnalités

Notepad++ est un outil très complet, ces principales fonctionnalités sont :

• Coloration syntaxique (PHP, Java, SQL, CSS, HTML, Javascript, YAML…)
• Éditeur WYSIWYG
• Auto-complétion
• Affichage de fichier et édition multiple simultanée
• Fonction de recherche avec expressions régulières
• Auto détection de modifications de fichiers
• Gestion de macros
• Zoom
• Multilingue

Vous trouverez toute la liste des fonctionnalités de Notepad++ sur le site de l’éditeur.

Plugins

Cette liste n’est pas exhaustive car en plus Notepad++ est extensible avec une très belle liste de plugins dont voici les plus intéressants à mon goût :

• Éditeur hexadécimal
• Édition de fichier via un explorateur FTP
• Gestionnaire de tags HTML
• Correcteur orthographique
• Réducteur dans la barre de tâches
• Édition XML (multiples outils)
• Gestionnaire de plugins

Astuces

Cet outil s’intègre parfaitement à Windows, vous pourrez ainsi le mettre dans le menu contextuel de Windows et y accéder via le clic droit de votre souris ou tout simplement l’utiliser par défaut à la place du bloc-notes de Windows.

Ces astuces sont à voir sur la page de téléchargement de l’application.

Site de l’éditeur & téléchargement

Vous pouvez télécharger Notepad++ sur le site de l’éditeur :

• Site officiel de Notepad++

Aide, forum et wiki

Si vous avez besoin d’aide pour débuter avec Notepad++, des forums multilingues et un wiki en anglais répondront probablement à toutes vos questions.

• Forums
• Wiki

Mon avis

Personnellement, je l’utilise depuis des années sans aucun soucis. Son ergonomie est très bonne, et ses plugins très nombreux permettent de répondre à toutes les attentes. Il est simple mais fonctionnel, vous le trouverez bientôt indispensable.

Et n’oublier pas, Notepad++ est un outil gratuit, pensez à aider le projet en traduisant ou en apportant une contribution financière.

Sur le même thème

• Outils XML : Cooktop
• Les plugins Firefox : XRefresh
• Comparaison et fusion de fichiers et de dossiers
• Les plugins Firefox : Colorzilla
• MySQL GUI Tools

Photo de batega depuis Flickr

Fonctionnalités

Il fonctionne pourtant parfaitement, je l’utilise depuis 5 ans sans problèmes sous Windows. Voici ses principales fonctionnalités :

• Édition de documents XML, DTD, et XSLT
• Coloration syntaxique du code XML, DTD, et XSLT
• Vérification de la validité du code XML
• Indentation automatique du code
• Test de feuille style XSLT
• Test d’expressions XPATH
• Formatage XML avec Tidy
• Léger et peu intrusif

Il reste à ma connaissance le seul outil gratuit et relativement complet pour l’édition de fichiers XML. Il existe aussi la solution d’Eclipse et de plugins que j’utilise également avec satisfaction, mais de façon plus basique.

Je teste actuellement le plugin Eclipse WTP.

Aide !

Je suis donc à la recherche d’un éditeur ayant les mêmes fonctionnalités, gratuit, si possible open-source et multi-plateformes afin de pouvoir l’utiliser à la maison comme au travail. Qu’utilisez vous pour éditer vos fichiers XML/XSL ?

Sur le même thème

• Outils : Edition de fichiers avec Notepad++
• Les plugins Firefox : XRefresh
• Comparaison et fusion de fichiers et de dossiers
• MySQL GUI Tools
• Navigateur Web standard : Firefox