Issues in the Spotify Web API reference documentation

[sonallux]

I have found out that the reference documentation for the Spotify Web API is sourced by the OpenAPI specification file from https://developer.spotify.com/_data/documentation/web-api/reference/open-api-schema.yml. While using the Spotify Web API for the last few years, I have found many inconsistencies between the OpenAPI spec file and the actual behavior of the endpoints. With this post, I want to share my collected inconsistencies with you and the Spotify Team to get the issues resolved and to make the experience using the Spotify Web API better.

- Minimum of `QueryLimit` Parameter should be 1 and not 0 at `$.components.parameters.QueryLimit.schema.minimum`
- Get Followed Artists endpoint (`GET /me/following`) can use `QueryLimit` definition from `$.components.parameters.QueryLimit` instead if defining it again.
- Get Playlist Items endpoint (`GET /playlists/{playlist_id}/tracks`) should not use the `QueryLimit` definition from `$.components.parameters.QueryLimit` because the maximum value of the `limit` parameter is 100 for this endpoint
- Get Recently Played Tracks endpoint (`GET /me/player/recently-played`) can use the `QueryLimit` definition from `$.components.parameters.QueryLimit` instead if defining it again.
- Save Episodes for Current User endpoint (`PUT /me/episodes`) should have marked request body parameter `ids` as required. Currently, a request body parameter `uris` is listed as required, but this parameter is not valid for this endpoint.
- Save Tracks for Current User endpoint (`PUT /me/tracks`) should have marked request body parameter `ids` as required. Currently, a request body parameter `uris` is listed as required, but this parameter is not valid for this endpoint.
- Add Custom Playlist Cover Image endpoint (`/playlists/{playlist_id}/images`) has no request body defined. I think the `requestBody` can be defined as:
  ```yml
  description: The new cover image of the playlist as a Base64 encoded JPEG
    image. Maximum payload size is 256KB.
  content:
    image/jpeg:
      schema:
        type: string
        format: base64
  required: true
  ```
- The definition of the `ManyDevices` response at `$.components.responses.ManyDevices` can be simplified and reuse the already existing `DevicesObject` at `$.components.schemas.DevicesObject`
  ```yml
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/DevicesObject'
  ```
- The schema of `OneCurrentlyPlayingTrack` response at `$.components.responses.OneCurrentlyPlayingTrack` should be `CurrentlyPlayingObject` and not `CurrentlyPlayingContextObject`
- The `AlbumObject` schema at `$.components.schemas.AlbumObject.allOf[1].properties` is missing the following properties:
  - `popularity` with type `integer`
  - `label` with type `string`
  - `external_ids` with type `$.components.schemas.ExternalIdObject`
  - `genres` with type array of `string`s
  - `copyrights` with type array of `$.components.schemas.CopyrightObject`s
- The property `artists` of the `AlbumObject` at `$.components.schemas.AlbumObject.allOf[1].properties.artists` should be an array of `$.components.schemas.SimplifiedArtistObject`s and not of `$.components.schemas.ArtistObject`s
- The schema of the property `show` of the `EpisodeObject` at `$.components.schemas.EpisodeObject.allOf[1].properties.show` is missing `allOf` around `$ref: '#/components/schemas/SimplifiedShowObject'`
- The definition of `SimplifiedAudiobookObject` schema at `$.components.schemas.SimplifiedAudiobookObject` can omit the second entry of the `allOf`
- The definition of `SimplifiedChapterObject` schema at `$.components.schemas.SimplifiedChapterObject` can omit the second entry of the `allOf`
- The definition of `SimplifiedEpisodeObject` schema at `$.components.schemas.SimplifiedChapterObject` can omit the second entry of the `allOf`
- The definition of `SimplifiedShowObject` schema at `$.components.schemas.SimplifiedShowObject` can omit the second entry of the `allOf`
- The definition of the `linked_track` property of the `TrackObject` at `$.components.schemas.TrackObject.properties.linked_from.allOf[0].$ref` should reference the `$.components.schemas.LinkedTrackObject` instead of the `TrackObject`

If someone is looking for a version of the OpenAPI specification file with all those issues resolved, have a look at my spotify-web-api repository on GitHub.