Pourquoi des requêtes sont rejetées

Toutes les requêtes ne sont pas les bienvenues

Jusqu'à présent, tous les appels API que vous avez effectués ont fonctionné. Vous avez envoyé une requête, vous avez reçu des données. Simple.

Mais ce n'est pas ainsi que fonctionnent la plupart des API réelles. Essayez celle-ci :

Vous devriez obtenir une erreur. Le serveur a refusé de répondre. Pas parce que l'URL est fausse, ni parce que le serveur est en panne. Il a refusé parce que vous n'avez pas prouvé qui vous êtes.

C'est ce qu'on appelle l'authentification. Et c'est l'un des aspects les plus courants que vous rencontrerez en travaillant avec des API.

Le problème de la connexion

En fait, vous comprenez déjà l'authentification. Chaque fois que vous vous connectez à un site web, vous saisissez votre e-mail et votre mot de passe. Le serveur les vérifie, confirme que vous êtes un utilisateur réel et vous laisse entrer. Sans cette étape, le serveur laisserait n'importe qui accéder au compte de n'importe qui.

Les API ont exactement le même problème. Elles ont besoin de savoir qui effectue la requête. Mais les API n'ont pas de formulaires de connexion. Il n'y a pas de champ de texte, pas de bouton "Se connecter". C'est juste une URL et des données.

Alors, comment se "connecter" à une API ? Vous joignez vos identifiants directement à la requête. Au lieu de taper un mot de passe dans un formulaire, vous incluez une chaîne de caractères spéciale (une clé API ou un jeton/token) dans la requête elle-même. Le serveur la lit, la vérifie et décide s'il doit répondre ou non.

Certains points de terminaison (endpoints) sont publics : n'importe qui peut les appeler, sans condition. C'est pourquoi GET /users/1 sur DummyJSON fonctionne sans aucune configuration. D'autres points de terminaison sont protégés : vous devez inclure des identifiants valides pour que le serveur accepte de répondre.

L'endpoint NewsAPI ci-dessus est protégé. Il nécessite une clé API pour savoir quel compte effectue la requête. Comme vous n'en avez pas inclus, il vous a rejeté.

401 vs 403 : deux types de refus

Vous avez vu un refus ci-dessus. Il existe en fait deux codes d'état pour dire "non", et ils signifient des choses différentes.

401 Unauthorized (Non autorisé) : "Je ne sais pas qui vous êtes." Vous n'avez pas fourni d'identifiants, ou ceux que vous avez fournis sont invalides. Vous vous êtes présenté sans pièce d'identité.

403 Forbidden (Interdit) : "Je sais qui vous êtes, mais vous n'avez pas le droit de faire ça." Vous vous êtes connecté avec succès, mais vous essayez d'accéder à quelque chose qui ne vous appartient pas. Vous avez une pièce d'identité, mais elle ne permet pas d'ouvrir cette porte.

En pratique :

• Vous avez oublié d'inclure votre clé API ? 401.
• Votre clé API est expirée ou mal orthographiée ? 401.
• Vous êtes connecté en tant qu'utilisateur standard mais vous essayez de supprimer le compte d'un autre utilisateur ? 403.
• Vous essayez d'accéder aux paramètres d'administration sans être administrateur ? 403.

Quand votre équipe technique dit "l'utilisateur reçoit une 401", vous savez maintenant exactement ce que cela signifie : la requête ne contient pas d'identifiants valides.

Authentification vs Autorisation

Ces deux mots se ressemblent et sont souvent confondus. Voici la différence.

L'authentification répond à la question : "Qui êtes-vous ?" C'est l'étape de connexion. Vous prouvez votre identité (avec un mot de passe, une clé, un token).

L'autorisation répond à la question : "Qu'avez-vous le droit de faire ?" Une fois que le serveur sait qui vous êtes, il vérifie vos droits d'accès.

L'authentification vient toujours en premier. On ne peut pas vérifier les permissions de quelqu'un si on ne sait pas de qui il s'agit. Une 401 signifie que l'authentification a échoué. Une 403 signifie que l'authentification a réussi, mais que l'autorisation a échoué.

Vous verrez ces deux notions dans la documentation des API. Quand la doc dit "cet endpoint nécessite une authentification", cela signifie que vous devez prouver qui vous êtes. Quand elle dit "nécessite des privilèges d'administrateur", c'est de l'autorisation en plus de l'authentification.

Comment les identifiants sont envoyés

Sur un site web, les identifiants passent par un formulaire de connexion. Avec les API, ils sont attachés à la requête. Il y a deux manières courantes de procéder.

Dans un en-tête (header) (l'approche la plus courante) :

Dans un paramètre de requête (query parameter) (plus simple, courant avec les clés API) :

Les en-têtes sont généralement préférés car les paramètres de requête peuvent se retrouver dans l'historique du navigateur, les journaux (logs) du serveur et les URL partagées. Cependant, de nombreuses API (Google Maps, NewsAPI, OpenWeatherMap) utilisent des paramètres de requête pour plus de simplicité. La documentation de l'API vous indique toujours laquelle utiliser.

Il existe différents types d'identifiants (clés API, tokens, OAuth), et nous les aborderons dans les prochaines leçons. Pour l'instant, l'essentiel à retenir est que : les API n'ont pas de formulaires de connexion, les identifiants sont donc directement attachés à la requête.

Points clés à retenir

• L'authentification est requise pour la plupart des endpoints d'API réels. Toutes les requêtes ne sont pas publiques.
• 401 Unauthorized signifie "Je ne sais pas qui vous êtes." Identifiants manquants ou invalides.
• 403 Forbidden signifie "Je sais qui vous êtes, mais vous ne pouvez pas faire ça." Permissions insuffisantes.
• Authentification = "qui êtes-vous ?" Autorisation = "que pouvez-vous faire ?"
• Les identifiants sont envoyés soit dans les headers, soit dans les query parameters, selon l'API.