diff --git a/docs/schema.yml b/docs/schema.yml index 21b77d10a..afca3812c 100644 --- a/docs/schema.yml +++ b/docs/schema.yml @@ -204,14 +204,6 @@ paths: description: Filter releases by artist schema: type: integer - - name: id - in: query - required: false - description: Filter releases by ID - schema: - type: array - items: - type: string - name: collection in: query required: false @@ -265,6 +257,41 @@ paths: $ref: "#/components/schemas/SimpleRelease" "401": $ref: "#/components/responses/Unauthorized" + /api/v2/release-groups: + get: + tags: + - Releases + summary: "Retrieve a list of release groups" + description: "Retrieve a list of all release groups on the server" + operationId: getReleaseGroups + parameters: + - $ref: "#/components/parameters/query" + - $ref: "#/components/parameters/pageParam" + - $ref: "#/components/parameters/pageSizeParam" + - name: primary_type + in: query + required: false + description: "Filter results by their primary type" + schema: + type: array + items: + $ref: "#/components/schemas/ReleaseTypeEnum" + responses: + "200": + description: Successful operation + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/Pagination" + - type: object + required: + - results + properties: + results: + type: array + items: + $ref: "#/components/schemas/ReleaseGroup" /api/v2/tags/podcasts: get: tags: @@ -634,9 +661,11 @@ components: guid: type: string format: uuid + description: "The globally unique ID of the listening object" createdDate: type: string format: date-time + description: "The date on which the listening was recorded" recording: $ref: "#/components/schemas/SimpleRecording" user: @@ -693,7 +722,18 @@ components: allOf: - $ref: "#/components/schemas/SimpleRelease" - type: object + required: + - artistCredit + - creationDate + - recordingCount + - duration + - attributedTo + - local + - releaseGroup + - recordings properties: + artistCredit: + $ref: "specs/multi-artist/schema.yml#/ArtistCredit" creationDate: type: string format: date-time @@ -708,49 +748,48 @@ components: $ref: "#/components/schemas/SimpleActor" local: type: boolean + releaseGroup: + $ref: "#/components/schemas/SimpleReleaseGroup" recordings: type: array items: $ref: "#/components/schemas/SimpleRecording" ReleaseGroup: - type: object - required: - - guid - - artist - - primaryType - properties: - guid: - type: string - format: uuid - artistCredit: - type: array - items: - $ref: "specs/multi-artist/schema.yml#/ArtistCredit" - primaryType: - $ref: "#/components/schemas/ReleaseTypeEnum" - secondaryType: - type: string - enum: - - compilation - - soundtrack - - spokenword - - interview - - audiobook - - audio-drama - - live - - remix - - dj-mix - - mixtape - - demo - - field-recording - releases: - type: array - items: - $ref: "#/components/schemas/SimpleRelease" + allOf: + - $ref: "#/components/schemas/SimpleReleaseGroup" + - type: object + required: + - guid + - artist + - releases + properties: + artistCredit: + type: array + items: + $ref: "specs/multi-artist/schema.yml#/ArtistCredit" + secondaryType: + type: string + enum: + - compilation + - soundtrack + - spokenword + - interview + - audiobook + - audio-drama + - live + - remix + - dj-mix + - mixtape + - demo + - field-recording + releases: + type: array + items: + $ref: "#/components/schemas/SimpleRelease" ReleaseTypeEnum: type: string default: album - description: The type of release + description: "The type of release" enum: - album - single @@ -815,7 +854,7 @@ components: SimpleRecording: type: object required: - - id + - guid - fid - name - playable @@ -824,8 +863,9 @@ components: - artist - cover properties: - id: - type: integer + guid: + type: string + format: uuid fid: type: string format: url @@ -846,13 +886,14 @@ components: SimpleRelease: type: object required: - - id + - guid - fid - name - local properties: - id: - type: integer + guid: + type: string + format: uuid fid: type: string format: url @@ -863,21 +904,36 @@ components: type: string playable: type: boolean - releaseGroup: - type: string - format: uuid cover: $ref: "#/components/schemas/CoverUrls" + SimpleReleaseGroup: + type: object + required: + - guid + - primaryType + properties: + guid: + type: string + format: uuid + description: "The unique identifier of the release group" + name: + type: string + primaryType: + $ref: "#/components/schemas/ReleaseTypeEnum" + releaseVersions: + type: integer + description: "The number of releases associated with this release group" SimpleUser: type: object required: - - id + - guid - username - fullUsername - avatar properties: - id: - type: integer + guid: + type: string + format: uuid username: type: string fullUsername: diff --git a/docs/specs/collections/schema.yml b/docs/specs/collections/schema.yml index b2668ba66..a6342b3f3 100644 --- a/docs/specs/collections/schema.yml +++ b/docs/specs/collections/schema.yml @@ -9,16 +9,25 @@ SimpleCollection: guid: type: string format: uuid + description: "The globally unique ID of the collection" name: type: string + description: "The user-defined name of the collection" local: type: boolean + description: "Whether the collection is hosted on the server the request is made against" owner: $ref: "../../schema.yml#/components/schemas/SimpleActor" Collection: allOf: - $ref: "#/SimpleCollection" - type: object + required: + - items properties: + description: + type: string + description: "The user-defined description of the collection" items: type: integer + description: "The total number of items in the collection" diff --git a/docs/specs/multi-artist/schema.yml b/docs/specs/multi-artist/schema.yml index 1c838add8..111b87b61 100644 --- a/docs/specs/multi-artist/schema.yml +++ b/docs/specs/multi-artist/schema.yml @@ -1,14 +1,16 @@ SimpleArtist: type: object required: - - id + - guid - fid - name - contentCategory - local properties: - id: - type: integer + guid: + type: string + format: uuid + description: "The globally unique ID of the artist" fid: type: string format: url @@ -32,16 +34,23 @@ Artist: allOf: - $ref: "#/SimpleArtist" - type: object + required: + - creationDate + - recordingCount + - releases properties: creationDate: type: string format: date-time + description: "The date on which the artist was added to the server" recordingCount: type: integer + description: "The number of recordings credited to the artist" tags: type: array items: type: string + description: "Any tags associated with the artist" releases: type: array items: @@ -54,7 +63,11 @@ ArtistCredit: properties: name: type: string - id: - type: integer + description: "The name of the artist" + guid: + type: string + format: uuid + description: "The globally unique ID of the artist" joinPhrase: type: string + description: "The phrase used to join this artist's name in the credits. For example: 'feat', '&', '+'"