HTTP, JSON et erreurs

Une API est une interface qu’un programme peut appeler. L’API locale d’Aède expose des données, pas un lecteur déjà dessiné. Les exemples supposent un serveur sur http://127.0.0.1:8787 ; adaptez le port à l’adresse affichée au démarrage.

Lire une adresse#

http://127.0.0.1:8787/api/v1/albums?limit=10 contient l’adresse de base, une route (/api/v1/albums) et un paramètre (limit=10). Plusieurs paramètres se séparent par &. Pour les espaces, accents, barres obliques et références, utilisez curl --get --data-urlencode :

curl --get 'http://127.0.0.1:8787/api/v1/album' \
  --data-urlencode 'name=Back in Black'

GET consulte les données. HEAD renvoie statut/en-têtes sans corps ; curl -I URL effectue un HEAD. Le catalogue accepte les deux. POST soumet une opération, PUT met à jour, PATCH modifie certains champs de compte et DELETE supprime/révoque. Les mutations existent seulement sur les routes administratives, d’authentification et personnelles documentées. Les options CLI --json, --output ou --csv ne sont pas des paramètres HTTP.

Lire une page de résultats#

Les listes possèdent cette enveloppe ; l’exemple illustre une page vide :

{"items":[],"total":0,"offset":0,"limit":50,"scanned_at":0}

items contient la page actuelle. total compte tous les résultats avant découpage. offset indique le nombre de résultats sautés, à partir de 0. limit est la taille maximale demandée : 50 par défaut, entre 1 et 200. La deuxième page de 50 résultats utilise offset=50&limit=50. Une page au-delà de la fin est une réussite avec une liste vide. Les filtres s’appliquent avant le tri, puis vient la pagination.

scanned_at donne la date du scan en secondes Unix. Comparez-la entre pages ; si elle change, recommencez la pagination lorsqu’une vue cohérente est nécessaire. Il n’existe pas d’instantané commun à plusieurs requêtes. Les durées en _ms sont en millisecondes et les tailles en octets. null signifie qu’un fait est indisponible ; un tableau vide indique l’absence de relations listées. Les noms conservent l’écriture locale. Un client doit ignorer les champs de réponse inconnus pour rester compatible avec les ajouts futurs.

Choisir une entité#

Une entité est un artiste, album, piste, enregistrement, œuvre, groupe de sorties, label ou genre. L’album est un release ; la piste place un recording dans cet album. Les réponses relient les entités avec un jeton stable reference. Copiez-le tel quel et transmettez-le par --data-urlencode ; n’inventez pas d’indices de tableau. Une référence de piste dépend du chemin et change lorsque le fichier est déplacé.

Les routes au singulier acceptent exactement l’un de ref ou name. La comparaison des noms ignore casse et accents ; une correspondance exacte normalisée passe avant une correspondance partielle. Les alias d’artistes sont reconnus. Pour les albums, enregistrements, œuvres et groupes de sorties, un identifiant MusicBrainz peut aussi être fourni dans name.

Si plusieurs entités correspondent, Aède renvoie 409 ambiguous_entity, avec au plus 200 candidats {reference,name} dans error.candidates. Répétez la requête avec le ref souhaité. Sans résultat, la réponse est 404 entity_not_found. Fournir les deux sélecteurs, aucun sélecteur, une référence du mauvais type ou des paramètres non pris en charge produit une erreur.

La navigation au singulier reprenant les commandes CLI résout les références alternatives acceptées vers la référence canonique actuelle avant de chercher l’attribution des sources. Choisir un artiste par un alias MBID non ambigu conserve donc la même origine sourcée qu’une sélection par nom.

Filtres et ordre#

Les filtres se combinent avec ET. Les listes ordinaires utilisent sort=catalog&order=asc par défaut : l’ordre déterministe enregistré lors du scan. Chaque route précise les autres tris acceptés. Les égalités de texte conservent l’ordre du catalogue. Les années inconnues d’albums restent à la fin dans les deux sens ; les années égales se départagent par titre normalisé, puis ordre du catalogue. Les filtres exacts mbid distinguent la casse. Pays et années ont un ordre fixe et refusent un autre tri.

Sur /albums, une référence stable artist, label ou genre sélectionne l’entité résolue, même si une autre entité porte le même nom. Les filtres par nom conservent leur correspondance partielle normalisée.

Les paramètres inconnus, répétés ou incompatibles sont refusés. /status et /library sont des exceptions historiques qui n’interprètent pas les paramètres ; n’en ajoutez pas plutôt que de dépendre de cette exception.

Les valeurs q, name et mbid du catalogue acceptent au plus 2048 octets UTF-8 après décodage de l’URL et avant normalisation. Les références stables, dont ref et les filtres par référence, acceptent au plus 16384 octets UTF-8. Les sélecteurs acceptant un nom ou une référence appliquent la limite de 2048 octets aux noms et celle de 16384 octets aux préfixes de types de référence reconnus ; les références doivent toujours avoir le type exigé par la route. Une valeur trop longue renvoie 400 invalid_query.

Les listes et détails du catalogue, y compris les routes d’origine /artists, /releases, /tracks, /recordings et /entities, partagent deux travailleurs bloquants avec la navigation, l’inspection et les opérations personnelles. À saturation, catalogue/navigation/inspection renvoient 429 inspection_busy ; les opérations personnelles renvoient 503 personal_busy. /status et /library lisent les métadonnées et compteurs de l’instantané en temps constant, hors de ce budget. L’authentification et l’admission du transport s’appliquent toujours.

Comprendre une erreur#

{"error":{"code":"entity_not_found","message":"no entity matches this reference"}}

Le statut HTTP décrit la catégorie de résultat. error.code est la valeur stable destinée aux logiciels ; le texte humain message peut changer.

Les erreurs d’authentification, de corps JSON et de tâches sont expliquées dans Administration, Tâches et Données personnelles. Les erreurs de transport/analyse HTTP et de négociation WebSocket ne garantissent pas cette enveloppe JSON.

La frontière locale#

Sans magasin de comptes à la première lecture dans un nouveau processus HTTP local, les lectures du catalogue ne demandent aucun jeton et peuvent révéler chemins, commentaires et noms aux autres processus/utilisateurs. Dès que le processus a observé le magasin, elles exigent une session Bearer ou, en HTTP local, le jeton administratif ; un magasin ensuite absent ou illisible ferme l’accès jusqu’à l’arrêt du processus. Redémarrer HTTP local sans magasin rétablit le mode de compatibilité anonyme. Un magasin illisible ferme l’accès même à la première lecture. HTTPS exige toujours des comptes, accepte seulement les sessions et valide Host/Origin contre son adresse configurée. HTTP reste limité à la boucle locale. Aucun transport n’autorise les origines tierces.

Les lectures natives de pochettes, paroles et formes d’onde revérifient l’accès après leur travail bloquant, avant de publier la réponse préparée. Une requête admise anonymement est refusée si les comptes sont activés pendant son attente ; une session capturée doit rester valide. Le jeton administratif local conserve son accès distinct du mode HTTPS, réservé aux sessions.

Aucun secret dans une page web ou URL. Le jeton administratif historique refuse toute Origin ; les sessions suivent la vérification d’origine du transport. Un futur lecteur/site nécessite encore une conception de connexion/cookies.

Choisir les routes#

Le contrat versionné de l’API définit la compatibilité et les types précis ; ces guides expliquent l’utilisation de l’interface actuellement implémentée.