sonallux / spotify-web-api

Tools for fixing and improving the official Spotify OpenAPI definition.

Spotify Web API Tools

This monorepo contains tools for fixing and improving the official Spotify OpenAPI definition. The fixed OpenAPI definition can be found in the fixed-spotify-open-api.yml file.

Modules

Module	Description
json-utils	Utility classes for JSON/YAML
spotify-web-api-open-api	Apply the fixes and improvements to the official OpenAPI definition

Versioning

Unfortunately Spotify does not provide any version information with their Web API reference documentation. Therefore, I do not follow semantic versioning when releasing new versions. Version do follow a schema based on the release date: <year>.<month>.<day> (e.g. a version released on 30th March 2021 will get the version number 2021.3.30).

Disclaimer

Because the documentation are only based on the Spotify Web API Reference, there might be difference to the actual behaviour of the Spotify Web API. Also, neither do I have any connections to Spotify nor am I an employee at Spotify.

How to release a new version

Just start the Release workflow in GitHub Actions or perform the following steps manually

1. Update the version number with ./mvnw versions:set -DnewVersion="<version>" -DgenerateBackupPoms=false
2. Run OpenApiGenerator to update the openapi definition with new version
3. Commit and push changes to GitHub
4. Wait till CI is green
5. Tag and push the commit created in step 1. A GitHub actions workflow will automatically deploy the artifacts to Maven Central.

spotify-web-api's Issues

Missing documentation of body parameters

According to this post in the Spotify Developer Forum the following two endpoint documentation is missing the ids body parameter:

• Remove User's Saved Shows
• Save Shows for Current User

Suggestion - id and uri properties on objects required by convention.

It would be great if all fields that weren't optional were marked as required, but I don't know a reliable way you make that determination from the documentation.

It would be nice if at least the id and uri fields on response objects were required. I think it is more justifiable than other fields to expect this since they are identifiers on the objects. From observation, the id and uri properties are never null when being returned from a request.

The benefit here is that clients that are generated from the specification won't make those two properties nullable. It's minor nuisance having null checks sprinkled throughout code that relies upon generated classes.

Thank you for your consideration.

(maybe all fields could be required unless the phrase "null" is in the description - that seems pretty cheesy though, and can be problematic given some array members can come back null.)

The new Developer for Spotify website

After ~1,5 half years using a real OpenAPI definition from Spotify, it was time for Spotify to completely rebuild the Developer for Spotify website (also see this blog post about some insights).

Unfortunately, this change also removed the underlying OpenAPI definition so I no longer have a source to apply my patches on 😟

First of all, I will continue to provide an OpenApi definition for Spotify. 🎉 I will start to reverse-engineer the website to extract the necessary information to build an OpenAPI definition. But please be patient as this will take some time 🙏

TrackObject.restrictions should be marked as optional?

I think that TrackObject.restrictions should be marked as optional, but I'm still learning the OpenAPI spec, so I may be wrong.

Example of a request/response pair missing the field:

curl --request GET  'https://api.spotify.com/v1/tracks/2TpxZ7JUBn3uw46aR7qd6V' --header "Authorization: Bearer $TOKEN"

{
  "album" : {
    "album_type" : "album",
    "artists" : [ {
      "external_urls" : {
        "spotify" : "https://open.spotify.com/artist/08td7MxkoHQkXnWAYD8d6Q"
      },
      "href" : "https://api.spotify.com/v1/artists/08td7MxkoHQkXnWAYD8d6Q",
      "id" : "08td7MxkoHQkXnWAYD8d6Q",
      "name" : "Tania Bowra",
      "type" : "artist",
      "uri" : "spotify:artist:08td7MxkoHQkXnWAYD8d6Q"
    } ],
    "available_markets" : [ "AD", "AE", "AG", "AL", "AM", "AO", "AR", "AT", "AU", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CG", "CH", "CI", "CL", "CM", "CO", "CR", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FR", "GA", "GB", "GD", "GE", "GH", "GM", "GN", "GQ", "GR", "GT", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN", "IQ", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MH", "MK", "ML", "MN", "MO", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NE", "NG", "NI", "NL", "NO", "NP", "NR", "NZ", "OM", "PA", "PE", "PG", "PH", "PK", "PL", "PS", "PT", "PW", "PY", "QA", "RO", "RS", "RW", "SA", "SB", "SC", "SE", "SG", "SI", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SZ", "TD", "TG", "TH", "TJ", "TL", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VN", "VU", "WS", "XK", "ZA", "ZM", "ZW" ],
    "external_urls" : {
      "spotify" : "https://open.spotify.com/album/6akEvsycLGftJxYudPjmqK"
    },
    "href" : "https://api.spotify.com/v1/albums/6akEvsycLGftJxYudPjmqK",
    "id" : "6akEvsycLGftJxYudPjmqK",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/ab67616d0000b2731ae2bdc1378da1b440e1f610",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/ab67616d00001e021ae2bdc1378da1b440e1f610",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/ab67616d000048511ae2bdc1378da1b440e1f610",
      "width" : 64
    } ],
    "name" : "Place In The Sun",
    "release_date" : "2004-02-02",
    "release_date_precision" : "day",
    "total_tracks" : 11,
    "type" : "album",
    "uri" : "spotify:album:6akEvsycLGftJxYudPjmqK"
  },
  "artists" : [ {
    "external_urls" : {
      "spotify" : "https://open.spotify.com/artist/08td7MxkoHQkXnWAYD8d6Q"
    },
    "href" : "https://api.spotify.com/v1/artists/08td7MxkoHQkXnWAYD8d6Q",
    "id" : "08td7MxkoHQkXnWAYD8d6Q",
    "name" : "Tania Bowra",
    "type" : "artist",
    "uri" : "spotify:artist:08td7MxkoHQkXnWAYD8d6Q"
  } ],
  "available_markets" : [ "AR", "AU", "AT", "BE", "BO", "BR", "BG", "CA", "CL", "CO", "CR", "CY", "CZ", "DK", "DO", "DE", "EC", "EE", "SV", "FI", "FR", "GR", "GT", "HN", "HK", "HU", "IS", "IE", "IT", "LV", "LT", "LU", "MY", "MT", "MX", "NL", "NZ", "NI", "NO", "PA", "PY", "PE", "PH", "PL", "PT", "SG", "SK", "ES", "SE", "CH", "TW", "TR", "UY", "US", "GB", "AD", "LI", "MC", "ID", "JP", "TH", "VN", "RO", "IL", "ZA", "SA", "AE", "BH", "QA", "OM", "KW", "EG", "MA", "DZ", "TN", "LB", "JO", "PS", "IN", "BY", "KZ", "MD", "UA", "AL", "BA", "HR", "ME", "MK", "RS", "SI", "KR", "BD", "PK", "LK", "GH", "KE", "NG", "TZ", "UG", "AG", "AM", "BS", "BB", "BZ", "BT", "BW", "BF", "CV", "CW", "DM", "FJ", "GM", "GE", "GD", "GW", "GY", "HT", "JM", "KI", "LS", "LR", "MW", "MV", "ML", "MH", "FM", "NA", "NR", "NE", "PW", "PG", "WS", "SM", "ST", "SN", "SC", "SL", "SB", "KN", "LC", "VC", "SR", "TL", "TO", "TT", "TV", "VU", "AZ", "BN", "BI", "KH", "CM", "TD", "KM", "GQ", "SZ", "GA", "GN", "KG", "LA", "MO", "MR", "MN", "NP", "RW", "TG", "UZ", "ZW", "BJ", "MG", "MU", "MZ", "AO", "CI", "DJ", "ZM", "CD", "CG", "IQ", "LY", "TJ", "VE", "ET", "XC", "XK" ],
  "disc_number" : 1,
  "duration_ms" : 276773,
  "explicit" : false,
  "external_ids" : {
    "isrc" : "AUCR10410001"
  },
  "external_urls" : {
    "spotify" : "https://open.spotify.com/track/2TpxZ7JUBn3uw46aR7qd6V"
  },
  "href" : "https://api.spotify.com/v1/tracks/2TpxZ7JUBn3uw46aR7qd6V",
  "id" : "2TpxZ7JUBn3uw46aR7qd6V",
  "is_local" : false,
  "name" : "All I Want",
  "popularity" : 1,
  "preview_url" : "https://p.scdn.co/mp3-preview/e8e668b5f6676b56dda747b6dac90aa3d2f5ad4a?cid=f681a8e934f143bab3a6965b6b73dd8e",
  "track_number" : 1,
  "type" : "track",
  "uri" : "spotify:track:2TpxZ7JUBn3uw46aR7qd6V"
}

Incorrect Response for Get Recommendations EndPoint

The documentation for Get Recommendations states that the response tracks array returns a SimplifiedTrackObject. From experience I see that it returns a TrackObject instead - that is it has the albums and popularity properties.

spotify-web-api/spotify-web-api-generator-open-api/spotify-web-api-openapi.yml

Line 6858 in c38c5c8

$ref: '#/components/schemas/SimplifiedTrackObject'

Missing content type in outputted yml.

For endpoint-reorder-or-replace-playlists-tracks
Line 4108

The 201 response for endpoint-reorder-or-replace-playlists-tracks has no content, therefore the default content of the error response is used. It should be SnapshotIdObject:

       content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotIdObject'

I haven't done Java in a while, but it looks like EndpointSplitter.java line 133 should be changed, replacing Void with SnapshotIdObject:

    List.of(new SpotifyWebApiEndpoint.ResponseType("SnapshotIdObject", 201, null))

Publish action does not create release notes

The publish action does not create the release notes (see this run). It does not work because the specified version range <latest-tag>...HEAD is empty, because the latest tag is normally the HEAD.

`AudiobookBase.narrators` is wrong

It's

type: array
$ref: '#/components/schemas/NarratorObject'

instead of

type: array
items:
  $ref: '#/components/schemas/NarratorObject'

No body parameters for playlists/{playlist_id}/images

The body parameter is missing for the endpoint playlists/{playlist_id}/images.

It should probably look something like this:

      requestBody:
        content:
          image/jpeg:
            schema:
              type: string
              format: base64 | binary ? // not quite sure which is really right

about use spotify openapi as demo

hi Jonas, sorry I use issues for this request since I cannot find a way to contact you.

Thanks for your work on spotify openapi spec.

We are doing an API collaboration service and we have implemented visual editor for openapi paths and components.

We will launch our service in the next a few months and we will be showing an image of editor on landing page. Becos our team think spotify spec is well maintained we would love to use it for our demo image, if that is ok for you.

The attached is a prototype for your reference.

Please let us know what you think, thanks.

Spotify's own Open API definition

The content of the Web API Reference is now sourced from an Open API definition published by Spotify: https://developer.spotify.com/_data/documentation/web-api/reference/open-api-schema.yml.

Currently, there is no official announcement about that change yet.

Actually, this should make this whole project obsolete now. BUT as I have already found some mistakes in the Open API definition, I maybe continue this project and provide a fixed Open API definition for the Web API. Initially, I could source the fixes by doing some kind of diff of my Open API definition and Spotify's Open API definition. With the list of fixes, I could fix Spotify's Open API definition and publish an improved Open API definition 🚀

OpenApi: Extract default, max and min value of numeric endpoint parameters

OpenAPI Specification allows defining a default, maximum and minimum value for schema objects. The Spotify Web API Reference contains this information for numeric parameters. The values could be extracted using this simple regex:

/(Default|Maximum|Minimum): (\d+)/gm

Generate models with a shared super type

The main Spotify objects (artist, album, track, playlist, show and episode) share a few common properties (id, type, href and uri). Therefore, I propose to have an abstract super type SpotifyObject which contains these four properties. It might be also beneficial to have shared super type for each individual type of main Spotify object.

This change would resolve to the following class hierarchy of all Spotify objects:

• SpotifyObject
  • BaseAlbum
    • Album
    • SimplifiedAlbum
  • BaseArtist
    • Artist
    • SimplifiedArtist
  • BaseEpisode
    • ...
  • BasePlaylist
    • ...
  • BaseUser
    • ...
  • BaseShow
    • ...
• other non main Spotify objects (e.g. Image, PlaylistTrack, ...)

Rename fixed-spotify.yml to fixed-spotify.yaml

Hello, first of all, thanks for this open API spec.
I'm currently using this tool to generate a dart lib for it.

They offer support to pull the specs directly via URL, however, there seems to be an issue with the .yml extension (idk why), so I wanted to ask if you could change the extension for the output file to ".yaml"?

It's just a convenience feature so if not also no problem.

Split endpoint-reorder-or-replace-playlists-tracks

With commit c3ae731 Spotify merged the reorder playlist tracks and replace playlist tracks endpoint into one endpoint as they share the same path and method (PUT /playlists/{playlist_id}/tracks).

This change made the endpoint description much more verbose and less usable to generate a nice Java API wrapper. Therefore I propose to manually split the endpoint-reorder-or-replace-playlists-tracks into a reorder and replace endpoint. Very similar to what I am currently doing with the endpoint-get-users-top-artists-and-tracks in the java generator.

The splitting logic should be moved out of the java generator as it might be beneficial for other generators too.

`SimplifiedTrackObject` missing `album` property

Hey 👋

Thanks for this project!

I've noticed that the SimplifiedTrackObject is missing an album property (SimplifiedAlbumObject).

I've manually added on my local version (line ~5382):

    SimplifiedTrackObject:
      type: object
      x-spotify-docs-type: SimplifiedTrackObject
      properties:
        album:
          allOf:
          - $ref: '#/components/schemas/SimplifiedAlbumObject'
          description: Information about the album.

It's also missing from the official definition from Spotify.

Is it worth adding it to your fixed version?

I read your comment on #114 and seems that we should start using the official Open API definition. Will you keep maintaining this version though while the official one has some mistakes?

Thank you again

Get a Playlist's Items - market is not required

Line 3884 of potify-web-api-openapi.yml begins the market parameter for /playlists/{playlist_id}/tracks. It is set as required, (and says so in the documentation), but it is not.

My guess is that you'd have to do something like the code below, but I can't tell where the right insertion point would be.

playlistTracksEndpoint.getParameters().stream().filter(p -> "market".equals(p.getName())).findFirst().get().setRequired(false);

Consider json patch for documentation fixes

JSON Patch (RFC 6902) defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. This could be used to express all our patches to the Spotify Web API Reference documentation in a standardized way because currently they are all hardcoded in Java.

There are two libraries that use Jackson to apply and generate such JSON Patches:

• zjsonpatch
• json-patch

Java generator: Union type handling

With the addition of Episodes and Shows, the Spotify Web API does use union types (for example can Playlists can contain Episodes and/or Tracks). As Java does not natively support unions, any union type is currently mapped to Map<String, Object>, which is not a nice UX.

Once shared super types are added (see #7) the handling of union types in the Java wrapper can be greatly improved.
For example the getPlaylistTrack() method can then be typed with a shared super type:

Paging<SpotifyObject> getPlaylistTracks(...) {
}

The user can then inspect the type property of the SpotifyObject and cast to either Track or Episode. This would require a custom Jackson deserializer that inspects the type property and then creates an instance of the concrete SpotifyObject class (e.g. Artist, Album, Track, Playlist, Show, Episode).