carnet

Ajouter une chanson a mon carnet

Ajoute une chanson au carnet PRIVE de l'appelant. Le corps porte le payload pivot canonique, exactement l'objet rendu par GET /jobs/{id}/result/songbook (songs[0]) ou par GET /me/songs/{songId} (song) : convertir puis ranger au carnet est donc un copier-coller, sans transformation.

IDENTIFIANT : il est DERIVE, jamais tire au sort. Dans l'ordre, song.id s'il est fourni, sinon le slug artiste-titre (la meme derivation que l'import dans l'application). Consequence utile : reposter deux fois la meme chanson REMPLACE la premiere au lieu de creer un doublon, et rend 200 plutot que 201.

PUBLICATION : un ajout ne publie JAMAIS sur le profil. Publier est une declaration explicite, une fois par objet ; elle se fait par PATCH /me/songs/{songId} avec publish et publishDeclaration.

IDEMPOTENCE : poser Idempotency-Key est recommande. Un rejeu EXACT (meme cle, meme corps) rend la MEME reponse en 200, sans consommer une seconde unite de quota ; la meme cle avec un corps different rend 422 idempotency-conflict.

Consomme UNE unite du compteur d'ECRITURE (write dans GET /me/usage), jamais une conversion ni une lecture.

post/me/songs

Request

  • Base URL: https://jam-jam.org/api/v1
  • URL: https://jam-jam.org/api/v1/me/songs
  • Auth: one of:
    • HTTP bearer
    • none

Headers

Idempotency-Keystring

Request body

songobject required

Payload pivot canonique. La meme forme que songs[0] de GET /jobs/{id}/result/songbook et que song de GET /me/songs/{songId} : title (obligatoire, non vide), artist, sections[].lines[].lyrics et .chords[] = { offset, chord }, detectedKey { tonic, scale }, metadata { capo, bpm, ... }. Validee par la MEME porte que l'import d'un fichier .jamsong dans l'application ; une forme invalide rend 422 unprocessable-entity avec le motif en clair.

Plafond DUR de 512 Ko (JSON serialise), sinon 413 payload-too-large.

playlistIdsstring[]

Etat CIBLE COMPLET des appartenances. La chanson est ajoutee aux playlists citees et RETIREE de toutes les autres. Omis = les appartenances ne bougent pas.

publishboolean

Reserve : une CREATION ne publie jamais par defaut. Publier passe par PATCH, avec publishDeclaration.

publishDeclaration'created' | 'imported_no_known_restriction' | 'arrangement'

Response

Chanson REMPLACEE (l'identifiant derive existait deja), ou rejeu idempotent d'une creation precedente.

idstring required

Identifiant stable de l'objet ecrit.

updatedAtstring date-time required

Horodatage serveur apres l'ecriture, en ISO 8601 UTC au millieme. C'est EXACTEMENT la valeur a renvoyer dans If-Match.

publishedboolean

Present UNIQUEMENT quand la requete portait publish : etat REEL de la publication apres l'ecriture. Un refus de publication n'est jamais un published: false silencieux, c'est un 409.

Changes

No recorded changes to this operation across all 1 revision of this API.