🌐 Référence REST – SwipeZ API

Cette page documente les principaux endpoints HTTP exposés par l’API SwipeZ, à partir du contrat OpenAPI 3.0.

L’API est organisée autour de plusieurs domaines :

API : endpoints techniques (santé du service).
Spotify : authentification, playlists, préférences.
Playlist : opérations détaillées sur les pistes d’une playlist.

Tous les exemples de réponses sont basés sur les modèles JSON définis dans le contrat (components.schemas).

🔐 1. Authentification & sessions (tag `Spotify`)

Ces endpoints gèrent le flux OAuth2 PKCE avec Spotify ainsi que le cycle de vie des sessions.

1.1 `POST /api/spotify/auth/start`

Démarre le flux OAuth2 PKCE côté serveur et renvoie l’URL d’autorisation Spotify ainsi que l’état associé.

Requête

Méthode : POST
URL : /api/spotify/auth/start
Headers :
- Content-Type: application/json
Body (AuthStartRequestDto) :

{
  "scopes": [
    "playlist-read-private",
    "playlist-modify-private"
  ]
}

Réponses

200 OK
Corps : AuthStartResponseDto

{
  "authorizationUrl": "https://accounts.spotify.com/authorize?...",
  "state": "a1b2c3d4"
}

400 Bad Request
Corps : ProblemDetails (erreur de validation ou de configuration).

1.2 `GET /api/spotify/callback`

Endpoint de callback utilisé par Spotify après validation de l’utilisateur. Gère l’échange code ↔ tokens et la création de session.

Requête

Méthode : GET
URL : /api/spotify/callback
Query params :

Nom	Type	Obligatoire	Description
`code`	string	non	Code d’autorisation retourné par Spotify
`state`	string	non	Valeur de protection contre les attaques CSRF
`device`	string	non	Identifiant ou type de device (par défaut `""`)

Réponses

200 OK
Corps : string (par ex. message ou redirection server-side selon implémentation).
400 Bad Request
Corps : ProblemDetails (code invalide, état incohérent, etc.).

1.3 `POST /api/spotify/logout`

Met fin à la session utilisateur, invalide les tokens associés (denylist) et nettoie les données liées à la session.

Requête

Méthode : POST
URL : /api/spotify/logout
Query params :

Nom	Type	Obligatoire	Description
`sessionId`	string	non	Identifiant de session à invalider

Réponses

204 No Content
Déconnexion réussie, aucune charge utile.
400 Bad Request
Corps : ProblemDetails (session introuvable, paramètre manquant ou invalide).

🎧 2. Playlists & préférences (tags `Spotify` & `Playlist`)

Ces endpoints permettent de lister les playlists de l’utilisateur, gérer ses préférences et manipuler les pistes d’une playlist.

2.1 `GET /api/spotify/playlists`

Récupère les playlists de l’utilisateur, avec pagination.

Requête

Méthode : GET
URL : /api/spotify/playlists
Headers :

Header	Type	Obligatoire	Description
`X-Session-Id`	string	non	Identifiant de session applicatif
`X-Page-Token`	string	non	Jeton de pagination (page suivante à récupérer)

Réponses

200 OK
Corps : PlaylistPageDto

{
  "items": [
    {
      "playlistId": "37i9dQZF1DXcBWIGoYBM5M",
      "name": "Today's Top Hits",
      "imageUrl": "https://i.scdn.co/image/...",
      "owner": "Spotify",
      "trackCount": 50,
      "selected": false,
      "snapshot_id": "abc123"
    }
  ],
  "nextPageToken": "page-2"
}

2.2 `GET /api/spotify/playlist-preferences`

Retourne la liste actuelle des playlists sélectionnées par l’utilisateur.

Requête

Méthode : GET
URL : /api/spotify/playlist-preferences
Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Réponses

200 OK
Corps : PlaylistPreferencesDto

{
  "playlistIds": [
    "37i9dQZF1DXcBWIGoYBM5M"
  ]
}

2.3 `PUT /api/spotify/playlist-preferences`

Remplace complètement la sélection de playlists.

Requête

Méthode : PUT
URL : /api/spotify/playlist-preferences
Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Body (PlaylistPreferencesDto) :

{
  "playlistIds": [
    "37i9dQZF1DXcBWIGoYBM5M",
    "6rqhFgbbKwnb9MLmUQDhG6"
  ]
}

Réponses

200 OK
Sélection enregistrée.

2.4 `DELETE /api/spotify/playlist-preferences`

Supprime toutes les préférences de playlists de l’utilisateur.

Requête

Méthode : DELETE
URL : /api/spotify/playlist-preferences
Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Réponses

200 OK
Aucune charge utile.

2.5 `PATCH /api/spotify/playlist-preferences/add`

Ajoute des playlists à la sélection existante.

Requête

Méthode : PATCH
URL : /api/spotify/playlist-preferences/add
Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Body (PlaylistPreferencesDto) :

{
  "playlistIds": [
    "37i9dQZF1DXcBWIGoYBM5M"
  ]
}

Réponses

200 OK

2.6 `PATCH /api/spotify/playlist-preferences/remove`

Retire des playlists de la sélection.

Requête

Méthode : PATCH
URL : /api/spotify/playlist-preferences/remove
Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Body (PlaylistPreferencesDto) :

{
  "playlistIds": [
    "37i9dQZF1DXcBWIGoYBM5M"
  ]
}

Réponses

200 OK

2.7 `GET /playlists/{playlistId}/tracks`

Récupère les pistes d’une playlist spécifique, avec pagination par offset.

Requête

Méthode : GET
URL : /playlists/{playlistId}/tracks
Path params :

Nom	Type	Obligatoire	Description
`playlistId`	string	oui	Identifiant de playlist

Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Query params :

Nom	Type	Obligatoire	Description
`offset`	int32	non	Index de départ (0, n)

Réponses

200 OK
Corps : PlaylistTracksDto

{
  "playlistId": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 50,
  "offset": 0,
  "nextOffset": 50,
  "tracks": [
    {
      "id": "6rqhFgbbKwnb9MLmUQDhG6",
      "name": "Track name",
      "artists": [
        { "id": "123", "name": "Artist" }
      ],
      "album": {
        "id": "456",
        "images": [
          { "url": "https://...", "width": 640, "height": 640 }
        ]
      },
      "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
    }
  ]
}

401 Unauthorized / 403 Forbidden / 429 Too Many Requests
Corps : ProblemDetails

2.8 `DELETE /playlists/{playlistId}/tracks`

Supprime une sélection de pistes d’une playlist Spotify.

Requête

Méthode : DELETE
URL : /playlists/{playlistId}/tracks
Path params :

Nom	Type	Obligatoire
`playlistId`	string	oui

Headers :

Header	Type	Obligatoire
`X-Session-Id`	string	non

Body (PlaylistTracksRemoveBody) :

{
  "tracks": [
    { "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" }
  ]
}

Réponses

200 OK
Corps : SnapshotResponse

{
  "snapshot_id": "snapshot-xyz"
}

401 Unauthorized / 403 Forbidden / 429 Too Many Requests
Corps : ProblemDetails.

🩺 3. Endpoint technique (tag `API`)

3.1 `GET /health`

Permet de vérifier rapidement que l’API est joignable.

Requête

Méthode : GET
URL : /health

Réponses

200 OK
Aucune charge utile spécifique (OK technique).

📦 4. Modèles JSON (schemas principaux)

4.1 `AuthStartRequestDto`

{
  "scopes": ["string", "..."]
}

scopes (string[], optionnel) : scopes Spotify demandés.

4.2 `AuthStartResponseDto`

{
  "authorizationUrl": "string",
  "state": "string"
}

authorizationUrl (string) : URL d’autorisation Spotify.
state (string) : valeur d’état pour sécuriser le flux.

4.3 `PlaylistItemDto`

{
  "playlistId": "string",
  "name": "string",
  "imageUrl": "string",
  "owner": "string",
  "trackCount": 50,
  "selected": true,
  "snapshot_id": "string"
}

4.4 `PlaylistPageDto`

{
  "items": [ /* PlaylistItemDto */ ],
  "nextPageToken": "string"
}

4.5 `PlaylistPreferencesDto`

{
  "playlistIds": ["string", "..."]
}

Représente la sélection actuelle de playlists par l’utilisateur.

4.6 `PlaylistTracksDto`

{
  "playlistId": "string",
  "limit": 50,
  "offset": 0,
  "nextOffset": 50,
  "tracks": [ /* SpotifyTrack */ ]
}

4.7 `PlaylistTracksRemoveBody`

{
  "tracks": [
    { "uri": "string" }
  ]
}

4.8 `SpotifyTrack`

{
  "id": "string",
  "name": "string",
  "artists": [ /* ArtistDto */ ],
  "album": {
    "id": "string",
    "images": [ /* SpotifyImage */ ]
  },
  "uri": "string"
}

4.9 `ArtistDto`

{
  "id": "string",
  "name": "string"
}

4.10 `AlbumDto`

{
  "id": "string",
  "images": [ /* SpotifyImage */ ]
}

4.11 `SpotifyImage`

{
  "url": "string",
  "height": 640,
  "width": 640
}

4.12 `SpotifyTracksUri`

{
  "uri": "string"
}

4.13 `SnapshotResponse`

{
  "snapshot_id": "string"
}

4.14 `ProblemDetails`

Schéma générique de description d’erreur.

{
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}

🔚 Remarques d’usage

Les endpoints qui manipulent des données utilisateur exigent en pratique un contexte de session valide (header X-Session-Id ou paramètre sessionId selon le cas).
Les codes 401, 403 et 429 renvoient tous un ProblemDetails structuré, ce qui permet un traitement homogène côté client.
Le contrat OpenAPI complet incluant tous les schémas doit rester la source de vérité pour la génération de clients automatiques.

🌐 Référence REST – SwipeZ API

🔐 1. Authentification & sessions (tag Spotify)

1.1 POST /api/spotify/auth/start

1.2 GET /api/spotify/callback

1.3 POST /api/spotify/logout

🎧 2. Playlists & préférences (tags Spotify & Playlist)

2.1 GET /api/spotify/playlists

2.2 GET /api/spotify/playlist-preferences

2.3 PUT /api/spotify/playlist-preferences

2.4 DELETE /api/spotify/playlist-preferences

2.5 PATCH /api/spotify/playlist-preferences/add

2.6 PATCH /api/spotify/playlist-preferences/remove

2.7 GET /playlists/{playlistId}/tracks

2.8 DELETE /playlists/{playlistId}/tracks

🩺 3. Endpoint technique (tag API)

3.1 GET /health

📦 4. Modèles JSON (schemas principaux)

4.1 AuthStartRequestDto

4.2 AuthStartResponseDto

4.3 PlaylistItemDto

4.4 PlaylistPageDto

4.5 PlaylistPreferencesDto

4.6 PlaylistTracksDto

4.7 PlaylistTracksRemoveBody

4.8 SpotifyTrack

4.9 ArtistDto

4.10 AlbumDto

4.11 SpotifyImage

4.12 SpotifyTracksUri

4.13 SnapshotResponse

4.14 ProblemDetails

🔚 Remarques d’usage

🔐 1. Authentification & sessions (tag `Spotify`)

1.1 `POST /api/spotify/auth/start`

1.2 `GET /api/spotify/callback`

1.3 `POST /api/spotify/logout`

🎧 2. Playlists & préférences (tags `Spotify` & `Playlist`)

2.1 `GET /api/spotify/playlists`

2.2 `GET /api/spotify/playlist-preferences`

2.3 `PUT /api/spotify/playlist-preferences`

2.4 `DELETE /api/spotify/playlist-preferences`

2.5 `PATCH /api/spotify/playlist-preferences/add`

2.6 `PATCH /api/spotify/playlist-preferences/remove`

2.7 `GET /playlists/{playlistId}/tracks`

2.8 `DELETE /playlists/{playlistId}/tracks`

🩺 3. Endpoint technique (tag `API`)

3.1 `GET /health`

4.1 `AuthStartRequestDto`

4.2 `AuthStartResponseDto`

4.3 `PlaylistItemDto`

4.4 `PlaylistPageDto`

4.5 `PlaylistPreferencesDto`

4.6 `PlaylistTracksDto`

4.7 `PlaylistTracksRemoveBody`

4.8 `SpotifyTrack`

4.9 `ArtistDto`

4.10 `AlbumDto`

4.11 `SpotifyImage`

4.12 `SpotifyTracksUri`

4.13 `SnapshotResponse`

4.14 `ProblemDetails`