Catégories
Start-up et applications

Comment concevoir avec empathie des API que les développeurs adoreront

La conception est importante dans de nombreux aspects du développement, ce qui est particulièrement vrai pour le développement qui stimule l'expérience utilisateur. Nous avons appris que la conception d'API peut avoir un impact profond sur les interfaces utilisateur et donc les expériences utilisateur. Des API mal conçues peuvent entraîner des flux de travail maladroits, non naturels ou inefficaces dans l'expérience d'un utilisateur, tandis qu'une API bien conçue peut atténuer ces problèmes ou au moins faire comprendre aux développeurs ce que tout est techniquement possible. En fin de compte, les interfaces utilisateur sont une représentation de l'API sous-jacente.

Voici cinq bonnes pratiques de conception, d'implémentation, de performances et de sécurité à garder à l'esprit lors de la production d'API.

Meilleure pratique: faites de votre API une priorité

Les API doivent être conçues et développées en gardant à l'esprit la simplicité, la cohérence et la facilité d'utilisation. Accomplir ces choses peut être facile dans un silo mais la vue du consommateur peut être radicalement différente car ses besoins ou ses désirs n'ont probablement pas été pris en compte. Il est toujours important de concevoir et d'itérer étroitement avec les consommateurs et / ou les clients avant de produire une implémentation à long terme. La meilleure façon d'y parvenir est de pratiquer l'API-First Design, une méthodologie de conception axée sur la collaboration avec les parties prenantes. Poursuivre avec l'alternative peut entraîner une API conforme au système existant ou simplement servir de canal vers la base de données sous-jacente qui ignorera presque toujours les workflows du client. Une grande analogie existe dans le monde de la construction – vous ne construiriez pas de maison et ne rédigeriez pas de plans.

De plus, en menant avec la conception d'API, il est possible d'identifier le format de spécification d'API et l'outillage dès le début. La spécification API doit être décrite dans un format établi tel que OpenAPI, API Blueprint ou RAML. Un format établi est susceptible d'avoir suffisamment d'outils que les clients connaissent comme Apiary, Redocly ou Swagger Hub. En fonction de l'écart de temps entre la conception de l'API et le développement du client, il peut être approprié d'envisager une fonctionnalité de simulation dont disposeront la plupart des outils établis. La simulation est un bon moyen de faire découvrir aux consommateurs potentiels des exemples de données pendant la mise en œuvre.

Meilleure pratique: structure avec une conception orientée ressources

Il existe un style architectural très commun connu sous le nom de REST qui est devenu la norme de facto sur les API depuis un certain temps maintenant. Les API développées à l'aide de l'architecture REST seraient RESTful. En général, REST fournit des contraintes architecturales importantes et bien connues mais manque de conseils concrets sur la création d'API. Il existe un style architectural étendu connu sous le nom de conception orientée ressources, satisfaisant toutes les contraintes de REST, qui sert de bonne référence de conception API. Si nous devons comparer REST à SQL, Resource Oriented Design fournit des propriétés de normalisation similaires à REST comme le font 2NF et 3NF pour SQL. Voici quelques contraintes à respecter:

  • le URI API doit être modélisé comme une hiérarchie de ressources où chaque nœud est une ressource ou une ressource de collection
    • Ressource – une représentation d'une entité dans l'application sous-jacente, par exemple / todo-lists / 1, / todo-lists / 1 / items / 1
    • Collection – une liste de ressources du même type, par exemple / todo-lists, / todo-lists / 1 / items
  • Le chemin URI – chemin de ressource – doit identifier de manière unique une ressource, par ex. / todo-lists / 1, / todo-lists / 56
  • Actions doit être géré par les méthodes HTTP

Le respect de ces contraintes dans la mesure du possible conduira à une API normalisée cohérente et prévisible. De plus, en laissant le verbiage exploitable hors des URI, il est plus facile de s'assurer que chaque chemin de ressource est une représentation d'une entité. C'est pourquoi les verbes sont désapprouvés pour les URI d'API RESTful car ils ne sont probablement pas une représentation d'une entité sous-jacente. Par exemple, / activate n'est probablement pas une ressource.

En ce qui concerne les ressources de données elles-mêmes, il n'y a pas de réponse universellement acceptée sur le format utilisé pour les représenter. JSON est largement adopté et compris par la majorité des plateformes. Cependant, XML ou d'autres formats peuvent tout aussi bien ou mieux servir les consommateurs dans certaines situations. L'essentiel est de représenter les ressources d'une manière rapide et facile à comprendre pour les consommateurs.

Représenter les ressources de cette manière leur permet de «parler» pour elles-mêmes, appelées ressources auto-descriptives. Des ressources auto-descriptives documentées à l'aide d'outils établis et de normes ouvertes créeront un sentiment de confiance avec le consommateur. En fin de compte, les consommateurs devraient adhérer à ce que l'API vend sans matériel supplémentaire "fluff".

Meilleure pratique: sémantique avec HTTP et REST

Pour donner vie à une API, elle doit être exploitable, d'autant plus qu'elle sera probablement utilisée pour informer l'interface utilisateur d'un client – les boutons doivent faire quelque chose. Les actions, dans le contexte de REST, doivent être accomplies par des méthodes HTTP chacune avec un objectif prévu qui est décrit ici:

  • AVOIR – requête / recherche de ressources, censées être idempotentes et donc pouvant être mises en cache
  • PUBLIER – sémantique REST la plus flexible, toutes les actions non idempotentes excluant les suppressions doivent être traitées par cette méthode
  • METTRE – utilisé pour modifier des ressources entières, mais devrait toujours être idempotent
  • PIÈCE – utilisé pour apporter des modifications partielles aux ressources, mais devrait toujours être idempotent
  • SUPPRIMER – supprime une ressource de l'API, doit être idempotent de la vue de l'appelant

De plus, le résultat de chaque action doit être renvoyé au client avec un code d'état approprié tel que défini par la norme HTTP. Votre API n'a pas besoin de prendre en charge tous les codes standard. Mais il peut supporter plus que vous ne le pensez. Voici quelques statuts courants qui seront probablement requis sur tout projet d'API:

  • Réponse réussie (200 – 399)
    • 200 – réponses avec un corps pour tout sauf une action de création
    • 201 – réponses pour les actions de création
    • 202 – réponses pour un long processus
    • 204 – réponses qui ne nécessitent pas de corps
  • Erreurs client (400 – 499)
    • 400 – requête invalide ou mauvaise, appropriée pour les erreurs syntaxiques
    • 401 – demande non authentifiée en raison d'informations d'identification manquantes, invalides ou expirées
    • 403 – autorisations insuffisantes (par exemple, mauvaise portée Oauth, nécessite des privilèges d'administrateur)
    • 404 – ressource non trouvée (par exemple, l'entité représentée n'existe pas dans la base de données)
    • 409 – conflit de ressources (par exemple, une ressource existe déjà)
    • 422 – la demande est syntaxiquement valide mais pas sémantiquement valide
  • Erreurs de serveur (500-599)
    • 500 – erreurs internes ou inconnues classiques pour la modélisation d'erreurs exceptionnelles / irrécupérables, d'erreurs sensibles ou d'erreurs qui ne peuvent pas être élaborées
    • 501 – méthode non implémentée
    • 503 – serveur indisponible
    • 504 – temps libre

Pour plus de clarté, une méthode HTTP idempotente peut être appelée plusieurs fois avec le même résultat. Les consommateurs devraient être en mesure de comprendre les informations, les relations et les opérations qu'une API fournit par les seules ressources et méthodes. Par exemple, une méthode GET qui crée ou une méthode PUT qui supprime une ressource entraînera une API imprévisible chargée d'effets secondaires inattendus. La méthode HTTP et les codes d'état appropriés, qui incluent naturellement des contraintes telles que l'idempotence, utilisés conjointement avec des ressources auto-décrites ne sont rien de plus que des représentations factuelles du domaine commercial sous-jacent.

Meilleure pratique: maintien des performances au niveau de la couche API

La création d'un service rapide nécessite une réflexion et une conception minutieuses, souvent au-delà de plusieurs frontières techniques. La liste des éléments à prendre en compte pour les performances peut aller d'une utilisation correcte de la concurrence dans l'application à une indexation de base de données adéquate. Cela dépend simplement des exigences et des besoins de l'entreprise. L'API peut maintenir les caractéristiques de performance du système sous-jacent de plusieurs manières, en voici quelques-unes à considérer:

  • Code serveur asynchrone – Les ressources qui sont un agrégat de plusieurs sources de données indépendantes peuvent être créées par le résultat de plusieurs résultats d'exécution asynchrone.
  • Implémentation non bloquante – Les API qui accèdent aux E / S froides, sont gourmandes en CPU ou tout simplement lentes devraient revenir avec un 202 pendant le traitement et indiquer au client où obtenir le résultat. Les Websockets et les rappels peuvent également être appropriés dans certaines situations.
  • Mise en cache – Les ressources qui changent relativement lentement peuvent être mises en cache. Les demandes GET idempotentes sont le fruit le plus bas. La mise en cache du niveau de service peut suffire mais un réseau de distribution de contenu (CDN) peut être nécessaire en fonction de la charge.
  • Pagination – Les ressources de collecte doivent être équipées de contrôles de pagination pour que le client limite les résultats
  • Apatridie – Le suivi de l'état des demandes peut être complexe et long pour le serveur. Idéalement, l'état doit être géré par le client et transmis au serveur. Cela s'applique également à l'authentification / autorisation. Les informations d'identification doivent être transmises à chaque demande. Le jeton Web JSON (JWT) est une bonne option.

Ces considérations contribueront grandement à atteindre des paramètres de performance satisfaisants définis par l'entreprise. Habituellement, la satisfaction des entreprises sera directement liée à la satisfaction de ses consommateurs. De nombreuses recherches ont montré que l'expérience utilisateur d'un consommateur est liée au temps de réponse d'une page. La latence du réseau joue un grand rôle dans le temps de chargement des pages, il est donc important de réduire ce temps autant que possible. Une bonne règle de base est de maintenir le temps de réponse API entre 150 et 300 millisecondes, qui est la plage de temps de réaction humain moyen.

Meilleure pratique: sécuriser votre API

Les informations personnelles et financières sont répandues sur Internet aujourd'hui. Il a toujours été important de protéger ces informations. Cependant, il y a eu de nombreuses violations de données notoires ces derniers temps qui font passer les considérations de sécurité d'une autre chose à des projets qui ne démarrent pas sans eux.

Il existe deux bonnes règles empiriques en matière de sécurité des API; ne vous embarrassez pas et ne réinventez pas la roue. Il est préférable de tirer parti des normes ouvertes telles que OAuth ou OpenID qui couvrent toutes deux la plupart des flux d'authentification. Il est également conseillé de déléguer les questions d'identité à des fournisseurs d'identité spécialement conçus tels que Auth0, Firebase ou Okta. La sécurité est une chose difficile à réaliser et les fournisseurs susmentionnés ont résolu ce défi et ont fait un effort supplémentaire. Quel que soit le standard et / ou le fournisseur utilisé, il est toujours important d'appliquer des contrôles d'accès appropriés aux ressources API. Les ressources sensibles doivent être verrouillées avec les informations d'identification appropriées et un 401 doit être renvoyé lorsque ces informations d'identification ne sont pas fournies. Dans les cas où un utilisateur donné n'a pas les privilèges adéquats sur une ressource, un 403 doit être retourné.

Les meilleures pratiques décrites ci-dessus sont des pratiques établies dans l'industrie qui devraient aider avec tout projet d'API. En adoptant une approche API-First, vous serez sur la bonne voie pour instaurer la confiance avec vos consommateurs et vos parties prenantes. La mise en pratique de la structure et de la sémantique REST établies ainsi que d'une sécurité adéquate seront des facteurs déterminants pour votre succès. Le maintien des performances incitera les consommateurs et les clients à revenir pour plus. En fin de compte, la conception d'API est à la fois un art et une science. Chaque API sera différente et il peut y avoir des décisions pragmatiques à prendre. Cependant, il est essentiel de ne pas trop s'éloigner des sentiers battus. Il est important de se rappeler que vos données et informations sont ce que recherchent réellement vos consommateurs et vos clients, pas votre nouvelle conception d'API radicale. Le respect de ces meilleures pratiques transmettra ces informations à vos clients les plus importants tout en gardant vos consommateurs informés tout au long du processus.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *