Créer de belles clés API

Résumé : Afin d'améliorer l'expérience des développeurs, AgentStation a créé le package uuidkey pour coder les UUID dans des clés API belles et faciles à lire. Ce package prend en charge UUIDv7 et peut décoder les clés pour le tri et l'indexation des bases de données.

Question :

Les clés API constituent une partie importante de la première interaction d'un utilisateur avec les produits AgentStation. Nous voulons que les clés soient belles et faciles à utiliser, mais il semble y avoir un manque de normes dans l'industrie. En tant que startup axée sur les développeurs, nous investissons du temps et des efforts pour trouver la solution idéale.

La plupart des clés API sont nulles :

Nous avons les exigences suivantes pour les clés API :

• Sécurité
• Unique au monde
• Triable
• Excellentes performances dans Postgres
• Belle apparence

Cependant, la plupart des clés API manquent d'esthétique et sont souvent des caractères aléatoires au format incohérent qui sont difficiles à lire, trier et identifier. Nous voulons que les clés API soient esthétiques et symétriques comme les bonnes choses de la vie.

Pièces d'identité que nous avons rejetées :

Trop aléatoire, facile à deviner, laid en apparence... tout cela insatisfaisant.

• Entiers et BigInt : Simple à lire et facile à trier. Mais ils révèlent le nombre de clés, sont faciles à deviner et n’offrent pas une sécurité suffisante.
• NanoIDs : Fournit des identifiants entièrement aléatoires et personnalisables, idéaux pour les identifiants publics. Mais il manque des informations d'horodatage pour le tri et le débogage.
• UUID : standard de l'industrie, avec deux versions à considérer :
  • UUIDv4 : Caractères purement aléatoires, simples et efficaces.
  • UUIDv7 : inclut un horodatage pour faciliter le débogage et le tri des requêtes de base de données.
• ULID : contiennent des horodatages et sont codés en Base32 pour une meilleure lisibilité. Mais nous préférons le support natif de Postgres UUID, et son esthétique est encore insuffisante.

Notre solution :

En raison du manque d'esthétique (symétrie) des solutions existantes, nous avons créé notre propre approche :

1. Utilisez UUIDv7 comme identifiant de base, en utilisant les informations d'horodatage.
2. Utilisez l'encodage Crockford Base32 pour améliorer la lisibilité.
3. Ajoutez de beaux tirets pour améliorer l'effet visuel.

Résultat :

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Notre clé :

• 31 caractères (28 sans tirets), plus courts que les 36 caractères d'un UUID.
• Paragraphe très lisible contenant 4 séries de 7 lettres et chiffres majuscules, avec une esthétique et une lisibilité « en blocs ».
• Peut être trié chronologiquement lorsqu'il est stocké sous forme d'UUID décodé.
• L'horodatage de la clé visible par l'utilisateur est obscurci (mais peut toujours être décodé par les utilisateurs avertis). Nous pensons que les métadonnées d'horodatage dans la clé sont un bonus supplémentaire, et vous pouvez également choisir d'utiliser UUIDv4 !

Pourquoi choisir UUIDv7 ?

En plus des avantages des horodatages, UUIDv7 bénéficiera d'un support natif dans Postgres v18. Bien qu'il soit actuellement possible de générer un UUIDv7 côté serveur à l'aide d'extensions, la prise en charge native de Postgres fonctionnerait certainement mieux et fonctionnerait bien avec uuidkey.Encode().

Dans notre implémentation, nous générons actuellement des clés au niveau de la couche application et les stockons sous forme d'UUID pour le tri et l'indexation. Une fois Postgres v18 publié, nous passerons aux versions Postgres pour réduire la charge sur la couche application et obtenir de meilleures performances.

Pourquoi choisir Crockford Base32 ?

Nous avons choisi l'encodage Crockford Base32 car il :

• Utilisez uniquement des lettres majuscules et des chiffres pour améliorer la lisibilité.
• Réduisez la longueur de la clé d'environ 1/5.
• La cartographie est efficace et prévisible.

Pourquoi utiliser Dash ?

Les touches tiret sont « en blocs » et symétriques. Si vous grisez les caractères individuels, ils ressemblent presque à un code-barres. Nous pensons que cela facilite la lecture rapide d'une partie d'une clé pour l'identifier.

Le tiret supprime la fonctionnalité pratique de copie par double-clic, mais nous pensons que c'est un compromis intéressant en termes de lisibilité. Nous ne voulons pas que les utilisateurs les copient et les collent partout, nous voulons en fait qu'ils soient traités avec soin. Idéalement, les utilisateurs ne copieraient une clé qu'une seule fois lors de sa génération dans notre tableau de bord. Nous avons donc ajouté un bouton de copie à l'interface utilisateur pour résoudre ce problème.

Pack uuidkey :

Nous avons ouvert ces choix de conception sur github.com/agentstation/uuidkey. Si vous êtes d'accord avec notre esthétique, notre raisonnement et notre symétrie et que vous souhaitez avoir votre propre clé API, n'hésitez pas à essayer notre projet open source.

uuidkey Le cœur du package est d'encoder un UUID dans un format de clé lisible via le codec Base32-Crockford et de le décoder en un UUID.

Encodage :

L'extrait de code a été donné dans le texte original et ne sera pas répété ici.

Décodage :

L'extrait de code a été donné dans le texte original et ne sera pas répété ici.

Le package est conçu pour fonctionner avec n'importe quel UUID qui suit la spécification officielle UUID (RFC 4122), mais nous testons et maintenons spécifiquement la compatibilité avec les deux générateurs UUID Go les plus populaires :

• Gofrs
• Google

L'installation est facile :

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Utilisation de base :

<code>go get github.com/agentstation/uuidkey</code>

Nous nous efforçons de réduire les frais généraux au minimum :

Les données des tests de référence de performances ont été fournies dans le texte original et ne seront pas répétées ici.

Contribuer à uuidkey :

Nous nous engageons à maintenir uuidkey comme un outil open source fiable car nous l'utilisons en production - les contributions sont les bienvenues !

Si vous le trouvez utile ou si vous avez des suggestions d'améliorations, nous serions ravis de vous entendre dans nos problèmes GitHub ou dans la communauté Discord.

La technologie antérieure et les épaules des géants :

Après avoir publié le projet, nous avons trouvé quelques projets avec des implémentations similaires, mais ne répondaient toujours pas à nos critères d'encodage et de décodage des UUID à l'aide de Go.

• uuidapikey - Go, mais ne prend pas en charge l'encodage ou le décodage de l'entrée UUID.
• based_uuid - Ruby, mais pour les identifiants publics.

Résumé :

Chez AgentStation, nous construisons une plate-forme qui permet aux agents IA de disposer de leur propre poste de travail virtuel pour exécuter des navigateurs, assister à des réunions et exécuter du code. À mesure que nous évoluons vers des milliers de postes de travail, disposer de clés triables et performantes constitue une infrastructure pratique.

Mais nous pensons également que les développeurs apprécient la beauté de la symétrie autant que nous, même dans les clés API.

Nous espérons que vous trouverez uuidkey à la fois pratique et beau.

Les notes de bas de page ont été données dans le texte original et ne seront pas répétées ici.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!