search

sonallux / spotify-web-api

Tools for fixing and improving the official Spotify OpenAPI definition.
MIT License
83 stars 9 forks source link

TrackObject.restrictions should be marked as optional? #230

Open miniBill opened 1 year ago

miniBill commented 1 year ago

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"
}
miniBill commented 1 year ago

(that response is also missing linked_from and is_playable, and some fields inside the authors too)

sonallux commented 1 year ago

Hi @miniBill, thanks for opening this issue. I am only adding patches on top of the official OpenAPI spec from Spotify. Unfortunately, the official spec does not provide this info. Manually adding this info without knowing the actual internals of the backing services, would be really costly and difficult. Therefore I can not currently provide this information.

This issue is quite similar to #113

miniBill commented 1 year ago

It kinda does tho? Notice the required vs lack of it? [got from https://developer.spotify.com/documentation/web-api/reference/#/operations/get-track]

image

sonallux commented 1 year ago

Ok, I had a close lock at this and it seems that Spotify does sometimes provide if a property is required or optional. But they do not provide the list of required properties for all objects. For example, the SimplifiedAlbumObject or AlbumBase object (where your screenshot is actually from) has a list of required properties, but the TrackObject does not have it.

Now I am considering adding the list of required properties where it is missing. So stay tuned for the next release.

miniBill commented 1 year ago

This is what I have so far:

--- build/spotify-web-api-original.yaml
+++ build/spotify-web-api-fixed.yaml
@@ -4785,6 +4785,14 @@
     PrivateUserObject:
       type: object
       x-spotify-docs-type: PrivateUserObject
+      required:
+      - display_name
+      - external_urls
+      - followers
+      - href
+      - id
+      - type
+      - uri
       properties:
         country:
           type: string
@@ -5609,6 +5617,8 @@
       allOf:
       - $ref: '#/components/schemas/PagingObject'
       - type: object
+        required:
+        - items
         properties:
           items:
             type: array
@@ -6022,6 +6032,19 @@
     SimplifiedPlaylistObject:
       type: object
       x-spotify-docs-type: SimplifiedPlaylistObject
+      required:
+      - id
+      - name
+      - description
+      - collaborative
+      - href
+      - images
+      - owner 
+      - public
+      - snapshot_id
+      - tracks
+      - type
+      - uri
       properties:
         collaborative:
           type: boolean
miniBill commented 1 year ago

Update:

--- build/spotify-web-api-original.yaml
+++ build/spotify-web-api-fixed.yaml
@@ -4451,6 +4451,8 @@
     ArtistObject:
       type: object
       x-spotify-docs-type: ArtistObject
+      required:
+      - name
       properties:
         external_urls:
           allOf:
@@ -4506,6 +4508,8 @@
     SimplifiedArtistObject:
       type: object
       x-spotify-docs-type: SimplifiedArtistObject
+      required:
+      - name
       properties:
         external_urls:
           allOf:
@@ -4554,6 +4558,8 @@
     PlaylistTrackObject:
       type: object
       x-spotify-docs-type: PlaylistTrackObject
+      required:
+      - track
       properties:
         added_at:
           type: string
@@ -4785,6 +4791,14 @@
     PrivateUserObject:
       type: object
       x-spotify-docs-type: PrivateUserObject
+      required:
+      - display_name
+      - external_urls
+      - followers
+      - href
+      - id
+      - type
+      - uri
       properties:
         country:
           type: string
@@ -5609,6 +5623,8 @@
       allOf:
       - $ref: '#/components/schemas/PagingObject'
       - type: object
+        required:
+        - items
         properties:
           items:
             type: array
@@ -5683,6 +5699,8 @@
       allOf:
       - $ref: '#/components/schemas/PagingObject'
       - type: object
+        required:
+        - items
         properties:
           items:
             type: array
@@ -6022,6 +6040,19 @@
     SimplifiedPlaylistObject:
       type: object
       x-spotify-docs-type: SimplifiedPlaylistObject
+      required:
+      - id
+      - name
+      - description
+      - collaborative
+      - href
+      - images
+      - owner 
+      - public
+      - snapshot_id
+      - tracks
+      - type
+      - uri
       properties:
         collaborative:
           type: boolean
@@ -6166,10 +6197,13 @@
     TrackObject:
       type: object
       x-spotify-docs-type: TrackObject
+      required:
+      - name
       properties:
         album:
-          allOf:
+          oneOf:
           - $ref: '#/components/schemas/SimplifiedAlbumObject'
+          - $ref: '#/components/schemas/LocalFileNoAlbumObject'
           description: |
             The album on which the track appears. The album object includes a link in `href` to full information about the album.
         artists:
@@ -6792,6 +6826,19 @@
               $ref: '#/components/schemas/SimplifiedArtistObject'
             description: |
               The artists of the album. Each artist object includes a link in `href` to more detailed information about the artist.
+    LocalFileNoAlbumObject:
+      type: object
+      required:
+      - type
+      properties:
+        type:
+          type: string
+        artists:
+          type: array
+          items:
+            $ref: '#/components/schemas/SimplifiedArtistObject'
+          description: |
+            The artists of the album. Each artist object includes a link in `href` to more detailed information about the artist.
     ChapterObject:
       x-spotify-docs-type: ChapterObject
       type: object

I've added a type for albums for local files, which don't respect the normal required of albums

sonallux commented 1 year ago

@miniBill Thanks for your work 👍

But I won't have time in the near future to review and integrate your changes, because Spotify has reworked its Spotify for Developer website. Please see #242 for more details. I will leave this issue open and when I have finished migrating to the new website I will revisit our proposals.

miniBill commented 1 year ago

No worries, I'm already incredibly grateful for all your work

miniBill commented 1 year ago

Hi! Any updates on this? :)