example-petstore.com

Domaine d’exemple · Pas un service réel · Les visites depuis un navigateur affichent cette page · Les requêtes API reçoivent 410 Gone

Guide · Documentation

Des valeurs d’exemple sans danger

La documentation, les tutoriels et les tests ont besoin d’adresses, de numéros et de noms qui semblent réels mais n’atteignent jamais personne. Pour la plupart des types de valeurs, une plage réservée existe. Ce guide les recense, chacune avec sa source, pour que les exemples restent inoffensifs quand quelqu’un les copie.

Pourquoi des valeurs réservées

Les exemples sont copiés : dans du code, des fichiers de configuration, des tests et d’autres documentations. Une valeur qui semble inventée mais appartient à quelqu’un envoie ce trafic, ces e-mails ou ces appels à un tiers bien réel. example-petstore.com en est l’illustration : un nom inventé dans la documentation de Google, que n’importe qui pouvait enregistrer, et qui reçoit encore des requêtes. Les valeurs réservées ne seront jamais attribuées, si bien qu’un exemple copié échoue sans conséquence.

Noms de domaine et e-mail

Pour les sites, les API et les adresses e-mail des exemples, utilisez example.com, example.net ou example.org et leurs sous-domaines, comme api.example.com et user@example.com. Pour les environnements de test, les noms qui ne doivent jamais être résolus et les réseaux locaux, il existe .test, .invalid, .localhost, home.arpa et .internal.

À quoi sert chaque nom réservé, et pourquoi des imitations comme example-petstore.com ne sont pas sûrs : Domaines d’exemple

Adresses IP

TypeRéservé à la documentationSource
IPv4192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), 203.0.113.0/24 (TEST-NET-3)RFC 5737
IPv62001:db8::/32RFC 3849
IPv6, réseaux plus grands3fff::/20RFC 9637 (2024)
 
# Un client, un serveur et un proxy dans un exemple
client   192.0.2.10        2001:db8::10
server   198.51.100.20     2001:db8:1::20
proxy    203.0.113.30      2001:db8:2::30

Les trois blocs IPv4 donnent à un exemple trois « réseaux » distincts, ce qui aide à expliquer le routage ou les pare-feu. 3fff::/20 existe parce que 2001:db8::/32 est trop petit pour montrer des allocations réalistes pour de grands fournisseurs.

Numéros AS

Pour les exemples BGP : 64496–64511 (16 bits) et 65536–65551 (32 bits), réservés à la documentation par la RFC 5398. Les numéros AS à usage privé sont destinés à de vrais réseaux, pas aux exemples.

Adresses MAC

Les adresses de 00-00-5E-00-53-00 à 00-00-5E-00-53-FF (écrites 00:00:5e:00:53:00 dans la plupart des outils) sont réservées à la documentation par la RFC 9542 (qui a remplacé la RFC 7042).

Numéros de téléphone

Il n’existe pas de plage mondiale ; plusieurs pays réservent la leur pour la fiction et les exemples :

  • États-Unis et Canada : de 555-0100 à 555-0199, avec n’importe quel indicatif régional, par exemple +1 202 555 0143.
  • Royaume-Uni (Ofcom) : mobiles de 07700 900000 à 07700 900999, Londres de 020 7946 0000 à 020 7946 0999, et de 01632 960000 à 01632 960999 sans zone géographique précise.

Pour les autres pays, consultez le régulateur des télécommunications. Là où aucune plage n’existe, utilisez un numéro fictif impossible à composer, comme +31 6 XXXX XXXX, plutôt que des chiffres qui ont seulement l’air aléatoires.

Cartes de paiement

Les prestataires de paiement publient des numéros de carte de test qui ne fonctionnent qu’en mode test, comme le 4242 4242 4242 4242 de Stripe, avec n’importe quelle date d’expiration future et n’importe quel CVC. Utilisez les numéros du prestataire que vous intégrez ; les numéros de test d’un prestataire ne sont pas acceptés par un autre. N’utilisez jamais un vrai numéro de carte, pas même le vôtre, dans la documentation, les fixtures ou les captures d’écran.

Ce qu’il ne faut pas utiliser

  • Des imitations inventées comme example-petstore.com, mycompany.com ou test.com : elles peuvent être enregistrées, et le sont souvent.
  • Des plages d’adresses privées comme 10.0.0.0/8 ou 192.168.0.0/16 dans une documentation publique : elles existent dans le propre réseau du lecteur, si bien qu’un exemple copié peut y atteindre un appareil réel.
  • Des clés d’API d’apparence réelle : écrivez une valeur fictive explicite comme YOUR_API_KEY ou sk_test_…, jamais une clé qui a été valide un jour.
  • Des données de personnes réelles : les noms, adresses e-mail et numéros de téléphone de collègues ou de clients n’ont pas leur place dans des exemples ou des fixtures de test.

Sources