musiclist-server/DOCS.md

# Documentación API

## Comunicación con MusicBrainz

Todos los links a continuación se mapean aproximadamente a lo que indica la documentación de 
[musicbrainz](https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2) utilizando su formato
de JSON

### Get

- `GET` `/api/brainz/get/artist/<mbid>/`

    Obtiene artista por su musicbrainz id, se puede incluir un parametro `inc` el cual agregara entidades
    relacionados al artista, estos deben ser separados por símbolos `+`, las entidades disponibles son:
    - `recordings` 
    - `releases`
    - `release-groups`
    Estas entidades relacionadas siempre estarán limitadas a 25.
    
    Ejemplo
   
    https://musiclist.danielcortes.xyz/api/brainz/get/artist/fa3b825f-7c85-4377-b393-d28a2016e293/?inc=releases+recordings
    
    
- `GET` `/api/brainz/get/release-group/<mbid>`

    Obtiene release-group por su musicbrainz id, se puede incluir un parametro `inc` el cual agregara entidades
    relacionados al release-group, estos deben ser separados por símbolos `+`, las entidades disponibles son:
    - `artists` 
    - `releases`
    Estas entidades relacionadas siempre estarán limitadas a 25.
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/get/release-group/86ac3ebd-2fee-49f7-a249-ddc6553970dd/?inc=releases
   
- `GET` `/api/brainz/get/release/<mbid>`

    Obtiene release por su musicbrainz id, se puede incluir un parametro `inc` el cual agregara entidades
    relacionados al release, estos deben ser separados por símbolos `+`, las entidades disponibles son:
    - `artists` 
    - `release-groups`  
    - `recordings`  
    Estas entidades relacionadas siempre estarán limitadas a 25.
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/get/release/8c2b980a-dbc4-4047-b637-c470c29a6e05/?inc=recordings+artists
    
- `GET` `/api/brainz/get/recording/<mbid>`

    Obtiene recording por su musicbrainz id, se puede incluir un parametro `inc` el cual agregara entidades
    relacionados al recording, estos deben ser separados por símbolos `+`, las entidades disponibles son:
    - `artists` 
    - `releases`  
    Estas entidades relacionadas siempre estarán limitadas a 25.
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/get/recording/051abadc-c78e-4fa1-a45e-1b24d6dab322/
    
### Search
    
- `GET` `/api/brainz/search/artist/`

    Busca un artista en la base de datos de musicbrainz, los parámetros disponibles son los siguientes:
    - `query`: Parámetro obligatorio el cual es un string con el que buscar
    - `limit`: Parámetro opcional para limitar la cantidad de resultados, por default es 25
    - `offset`: Parametro opcional para realizar paginado, por default es 0
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/search/artist/?query=in%20love%20with%20a%20ghost
    
- `GET` `/api/brainz/search/release-group/`

    Busca un release-group en la base de datos de musicbrainz, los parámetros disponibles son los siguientes:
    - `query`: Parametro obligatorio el cual es un string con el que buscar
    - `limit`: Parametro opcional para limitar la cantidad de resultados, por default es 25
    - `offset`: Parametro opcional para realizar paginado, por default es 0
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/search/release-group/?query=sizzlar&limit=1
    
- `GET` `/api/brainz/search/release/`

    Busca un release en la base de datos de musicbrainz, los parámetros disponibles son los siguientes:
    - `query`: Parametro obligatorio el cual es un string con el que buscar
    - `limit`: Parametro opcional para limitar la cantidad de resultados, por default es 25
    - `offset`: Parametro opcional para realizar paginado, por default es 0
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/search/release/?query=no&limit=10&offset=30
    
- `GET` `/api/brainz/search/recording/`

    Busca un release en la base de datos de musicbrainz, los parámetros disponibles son los siguientes:
    - `query`: Parametro obligatorio el cual es un string con el que buscar
    - `limit`: Parametro opcional para limitar la cantidad de resultados, por default es 25
    - `offset`: Parametro opcional para realizar paginado, por default es 0
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/search/recording/?query=no%20shade

### Browse

- `GET` `/api/brainz/browse/artist/`

    Busca un artista dada una serie de parámetros, como por ejemplo, obtener un artista de la release
    efac54db-1ff9-4ca4-a220-df2b155f3eb9. Sus parámetros son los siguientes
    - `inc`: Parametro opcional para indicar los datos a incluir junto a los artistas encontrados, disponibles:
        - `aliases`
    - `limit`: Parametro opcional para indicar el limite de resultados, por default es 25
    - `offstet`: Parametro opcional para realizar paginado, por default es 0
    
    Las entidades con las que se puede buscar son las siguientes:
    - `release-group`
    - `release`
    - `recording`
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/browse/artist/?recording=f059b12d-4379-4c4b-93eb-3a1f8026aa3b&release-group=37159cad-447e-4a71-bac4-9ef27e07d35b
    
    
- `GET` `/api/brainz/browse/release-group/`

    Busca una release-group dada una serie de parámetros, como por ejemplo, obtener la release-group
    de la release efac54db-1ff9-4ca4-a220-df2b155f3eb9. Sus parámetros son los siguientes
    - `inc`: Parametro opcional para indicar los datos a incluir junto a las release-group encontradas, disponibles:
        - `artist-credits`
    - `limit`: Parametro opcional para indicar el limite de resultados, por default es 25
    - `offstet`: Parametro opcional para realizar paginado, por default es 0
    
    Las entidades con las que se puede buscar son las siguientes:
    - `artist`
    - `release`
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/browse/release-group/?release=67459555-dddd-3af4-9f45-b07ae5545caa
    
- `GET` `/api/brainz/browse/release/`

    Busca una release dada una serie de parámetros, como por ejemplo, obtener las releases del artista
    fa3b825f-7c85-4377-b393-d28a2016e293. Sus parámetros son los siguientes
    - `inc`: Parametro opcional para indicar los datos a incluir junto a las release-group encontradas
    - `limit`: Parametro opcional para indicar el limite de resultados, por default es 25
    - `offstet`: Parametro opcional para realizar paginado, por default es 0
    
    Las entidades con las que se puede buscar son las siguientes:
    - `artist`
    - `release-group`
    - `recording`
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/browse/release/?artist=65f4f0c5-ef9e-490c-aee3-909e7ae6b2ab
    
- `GET` `/api/brainz/browse/recording/`

    Busca una recording dada una serie de parámetros, como por ejemplo, obtener las recordings del artista
    fa3b825f-7c85-4377-b393-d28a2016e293. Sus parámetros son los siguientes
    - `inc`: Parametro opcional para indicar los datos a incluir junto a las release-group encontradas
    - `limit`: Parametro opcional para indicar el limite de resultados, por default es 25
    - `offstet`: Parametro opcional para realizar paginado, por default es 0
    
    Las entidades con las que se puede buscar son las siguientes:
    - `artist`
    - `release`
    
    Ejemplo 
    
    https://musiclist.danielcortes.xyz/api/brainz/browse/recording/?artist=65f4f0c5-ef9e-490c-aee3-909e7ae6b2ab&release=d2891587-1be3-3b43-b80e-d6afd960ad08

### Cover Art

- `GET` `/api/brainz/coverart/release-group/<mbid>/<int:size>/`
    
    Busca el cover art de un release-group por su mbid, opcionalmente se le puede incluir el tamaño del cover art,
    que puede ser 250, 500, 1200
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/coverart/release-group/325b927d-72df-4e71-a5f9-7c717f72fb42/
    
- `GET` `/api/brainz/coverart/release/<mbid>/<int:size>/`
    
    Busca el cover art de una release por su mbid, opcionalmente se le puede incluir el tamaño del cover art,
    que puede ser 250, 500, 1200
    
    Ejemplo
    
    https://musiclist.danielcortes.xyz/api/brainz/coverart/release/887ea51a-71de-4628-8f02-b061f6904a64/1200