feat: initial implementation of metadata aggregator

- gRPC service with MusicBrainz provider - PostgreSQL schema with migrations - Service layer with database-first caching - Repository pattern for data access - YAML configuration support - Research documentation for 17 music metadata projects
2026-04-28 16:27:14 +02:00
commit a1f6701bac
163 changed files with 95884 additions and 0 deletions
@@ -0,0 +1,416 @@
+# MusicBrainz Server API
+
+## Base Endpoint
+
+`/ws/2/{entity}/{mbid}`
+
+**Version:** 2 (current stable)  
+**Protocol:** HTTPS (HTTP redirects to HTTPS)  
+**Base URL:** `https://musicbrainz.org/ws/2/`
+
+## Endpoint Reference
+
+### Core Entities (13)
+
+| Entity | Endpoint | Description |
+|--------|----------|-------------|
+| artist | `/ws/2/artist/{mbid}` | Artists, bands, orchestras, choirs, characters |
+| release | `/ws/2/release/{mbid}` | Physical or digital release of recordings |
+| recording | `/ws/2/recording/{mbid}` | Unique audio recording |
+| release-group | `/ws/2/release-group/{mbid}` | Logical grouping of releases |
+| work | `/ws/2/work/{mbid}` | Musical composition or song |
+| label | `/ws/2/label/{mbid}` | Record label or imprint |
+| area | `/ws/2/area/{mbid}` | Geographic region (country, city, etc.) |
+| event | `/ws/2/event/{mbid}` | Concert, festival, or other music event |
+| place | `/ws/2/place/{mbid}` | Venue, studio, or other location |
+| series | `/ws/2/series/{mbid}` | Ordered sequence of entities |
+| instrument | `/ws/2/instrument/{mbid}` | Musical instrument |
+| genre | `/ws/2/genre/{mbid}` | Music genre |
+| url | `/ws/2/url/{mbid}` | External URL relationship |
+
+### Identifier Lookups (3)
+
+| Lookup | Endpoint | Description |
+|--------|----------|-------------|
+| discid | `/ws/2/discid/{discid}` | CD table of contents lookup |
+| isrc | `/ws/2/isrc/{isrc}` | International Standard Recording Code |
+| iswc | `/ws/2/iswc/{iswc}` | International Standard Musical Work Code |
+
+### User Data Endpoints
+
+| Endpoint | Methods | Description |
+|----------|---------|-------------|
+| `/ws/2/collection` | GET, POST, PUT, DELETE | User collections |
+| `/ws/2/{entity}/{mbid}/tags` | GET, POST | User tags |
+| `/ws/2/{entity}/{mbid}/ratings` | GET, POST | User ratings (0-100) |
+| `/ws/2/{entity}/{mbid}/annotation` | GET | User annotations |
+
+## HTTP Methods
+
+### GET - Lookup
+
+Retrieve a single entity by MBID:
+
+```
+GET /ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da
+```
+
+### GET - Browse
+
+Browse entities related to another entity:
+
+```
+GET /ws/2/release?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da
+```
+
+### GET - Search
+
+Search entities using Lucene query syntax:
+
+```
+GET /ws/2/artist?query=artist:nirvana AND country:US
+```
+
+### POST - Submit
+
+Submit new data (requires authentication):
+
+```
+POST /ws/2/recording/{mbid}?client={client_id}
+Content-Type: application/json
+
+{
+  "isrcs": ["USRC17607839"]
+}
+```
+
+### PUT - Add to Collection
+
+Add entities to a collection (semicolon-separated MBIDs):
+
+```
+PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
+```
+
+### DELETE - Remove from Collection
+
+Remove entities from a collection:
+
+```
+DELETE /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2}
+```
+
+## Query Parameters
+
+### Format Parameter
+
+**Parameter:** `fmt`  
+**Values:** `xml`, `json`  
+**Default:** `xml`
+
+```
+/ws/2/artist/{mbid}?fmt=json
+```
+
+### Include Parameters (inc)
+
+Control which related data to include in the response. Multiple values separated by `+`.
+
+**Common Includes (all entities):**
+- `aliases` - Alternative names
+- `annotation` - Latest annotation
+- `tags` - Folksonomy tags
+- `user-tags` - Tags submitted by authenticated user
+- `genres` - Genre tags
+- `user-genres` - Genres submitted by authenticated user
+- `ratings` - Average rating
+- `user-ratings` - Rating submitted by authenticated user
+
+**Entity-Specific Includes:**
+
+**Artist:**
+- `recordings` - Recordings by this artist
+- `releases` - Releases by this artist
+- `release-groups` - Release groups by this artist
+- `works` - Works by this artist
+- `artist-rels` - Relationships to other artists
+- `label-rels` - Relationships to labels
+- `recording-rels` - Relationships to recordings
+- `release-rels` - Relationships to releases
+- `release-group-rels` - Relationships to release groups
+- `url-rels` - Relationships to URLs
+- `work-rels` - Relationships to works
+
+**Release:**
+- `artist-credits` - Artist credits for the release
+- `labels` - Labels for the release
+- `recordings` - Recordings on the release
+- `release-groups` - Release group for this release
+- `media` - Media (discs) in the release
+- `discids` - Disc IDs associated with the release
+- `isrcs` - ISRCs for recordings on the release
+
+**Recording:**
+- `artist-credits` - Artist credits for the recording
+- `releases` - Releases containing this recording
+- `isrcs` - ISRCs for this recording
+- `work-rels` - Works this recording is a performance of
+
+**Release Group:**
+- `artist-credits` - Artist credits for the release group
+- `releases` - Releases in this group
+
+**Work:**
+- `artist-rels` - Artists related to this work (composers, lyricists)
+- `recording-rels` - Recordings of this work
+
+**Example:**
+```
+/ws/2/release/{mbid}?inc=artist-credits+labels+recordings+media
+```
+
+### Browse Parameters
+
+Browse entities related to another entity:
+
+**Parameters:**
+- `artist={mbid}` - Browse by artist
+- `release={mbid}` - Browse by release
+- `release-group={mbid}` - Browse by release group
+- `recording={mbid}` - Browse by recording
+- `work={mbid}` - Browse by work
+- `label={mbid}` - Browse by label
+- `area={mbid}` - Browse by area
+- `collection={mbid}` - Browse by collection
+- `track_artist={mbid}` - Browse by track artist
+
+**Example:**
+```
+/ws/2/recording?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da&limit=100
+```
+
+### Pagination Parameters
+
+**Parameters:**
+- `limit` - Number of results (max 100, default 25)
+- `offset` - Starting offset (default 0)
+
+**Example:**
+```
+/ws/2/artist?query=nirvana&limit=100&offset=100
+```
+
+### Search Parameter
+
+**Parameter:** `query`  
+**Syntax:** Lucene query syntax
+
+**Example:**
+```
+/ws/2/artist?query=artist:nirvana AND country:US AND type:group
+```
+
+## Response Formats
+
+### XML Format
+
+**Namespace:** `http://musicbrainz.org/ns/mmd-2.0#`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
+  <artist id="5b11f4ce-a62d-471e-81fc-a69a8278c7da" type="Group">
+    <name>Nirvana</name>
+    <sort-name>Nirvana</sort-name>
+    <country>US</country>
+    <life-span>
+      <begin>1987</begin>
+      <end>1994-04-05</end>
+      <ended>true</ended>
+    </life-span>
+  </artist>
+</metadata>
+```
+
+### JSON Format
+
+```json
+{
+  "id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
+  "type": "Group",
+  "name": "Nirvana",
+  "sort-name": "Nirvana",
+  "country": "US",
+  "life-span": {
+    "begin": "1987",
+    "end": "1994-04-05",
+    "ended": true
+  }
+}
+```
+
+## Authentication
+
+### OAuth2 Bearer Token
+
+**Primary authentication method for user-specific operations.**
+
+**Header:**
+```
+Authorization: Bearer {access_token}
+```
+
+**Token Endpoint:** `https://musicbrainz.org/oauth2/token`  
+**Authorization Endpoint:** `https://musicbrainz.org/oauth2/authorize`
+
+**Grant Types:**
+- Authorization Code (with PKCE)
+- Refresh Token
+
+### HTTP Digest Authentication
+
+**Legacy authentication method, still supported.**
+
+**Header:**
+```
+Authorization: Digest username="user", realm="musicbrainz.org", ...
+```
+
+## OAuth Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `profile` | Read user profile information |
+| `email` | Read user email address |
+| `tag` | Submit and modify tags |
+| `rating` | Submit and modify ratings |
+| `collection` | Create and modify collections |
+| `submit_barcode` | Submit barcodes to releases |
+| `submit_isrc` | Submit ISRCs to recordings |
+
+## Rate Limiting
+
+**Limits:**
+- Maximum 100 items per page
+- 1 request per second (recommended)
+- Client identification required for POST requests
+
+**Client Identification:**
+
+All POST requests must include a `client` parameter:
+
+```
+POST /ws/2/recording/{mbid}?client=MyApp-1.0
+```
+
+**Format:** `{application_name}-{version}`
+
+**Rate Limit Headers:**
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1609459200
+```
+
+## CORS Support
+
+**Enabled:** Yes  
+**Allowed Origins:** `*`  
+**Allowed Methods:** GET, POST, PUT, DELETE  
+**Allowed Headers:** Authorization, Content-Type
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 400 | Bad Request - Invalid parameters or malformed request |
+| 401 | Unauthorized - Authentication required |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Entity does not exist |
+| 405 | Method Not Allowed - HTTP method not supported for this endpoint |
+| 406 | Not Acceptable - Requested format not available |
+| 415 | Unsupported Media Type - Invalid Content-Type |
+| 501 | Not Implemented - Feature not yet implemented |
+| 503 | Service Unavailable - Server overloaded or maintenance |
+
+**Error Response (JSON):**
+```json
+{
+  "error": "Not Found",
+  "help": "For usage, please see: https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2"
+}
+```
+
+## Example Requests
+
+### Lookup Artist with Releases
+
+```
+GET /ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da?inc=releases+release-groups&fmt=json
+```
+
+### Search for Recordings
+
+```
+GET /ws/2/recording?query=recording:"Smells Like Teen Spirit" AND artist:nirvana&fmt=json
+```
+
+### Browse Releases by Artist
+
+```
+GET /ws/2/release?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da&limit=100&offset=0&fmt=json
+```
+
+### Submit ISRC
+
+```
+POST /ws/2/recording/5b11f4ce-a62d-471e-81fc-a69a8278c7da?client=MyApp-1.0
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "isrcs": ["USRC17607839"]
+}
+```
+
+### Add Releases to Collection
+
+```
+PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
+Authorization: Bearer {token}
+```
+
+## Collection Management
+
+Collections allow users to organize entities (releases, artists, etc.).
+
+**List User Collections:**
+```
+GET /ws/2/collection?fmt=json
+Authorization: Bearer {token}
+```
+
+**Get Collection Contents:**
+```
+GET /ws/2/collection/{collection_mbid}/releases?fmt=json
+```
+
+**Add to Collection (semicolon-separated MBIDs):**
+```
+PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
+```
+
+**Remove from Collection:**
+```
+DELETE /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2}
+```
+
+## Best Practices
+
+1. **Always include a User-Agent header** identifying your application
+2. **Respect rate limits** - 1 request per second recommended
+3. **Use client parameter** for all POST requests
+4. **Cache responses** when appropriate
+5. **Use inc parameters** to minimize requests
+6. **Handle errors gracefully** with exponential backoff
+7. **Use HTTPS** for all requests (HTTP redirects to HTTPS)