Introduction

Last update: 2021-02-05

Based on simple REST principles, the Musimap Web API endpoints return JSON metadata about music artists, albums and tracks, directly from the provided catalogue.

The base address of our Web API is https://api-v2.musimap.io. The API provides a set of endpointsm each with its own unique path. To access data through the Web API, an application must be configured. Authorization is via the Musimap Authentication Stack.

A full documentation is available here. This is described under the openAPI format and you could retrieve the full JSON by running the following command:

curl --location --request OPTIONS 'https://api-v2.musimap.io/' 

Requests

The Musimap Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Musimap Web API uses appropriate HTTP vers for each action:

Method	Action
GET	Retrieves resources
POST	Creates resources
PATCH	Updates resources
DELETE	Deletes resoruces

Rate Limiting

Rate Limiting enables Web API to share access bandwidth to its resources equally across all clients.

Rate limiting is applied as per application based on Client ID, and regardless of the number of users who use the application simultaneously.

Note: If Musimap Web API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait, before you try your request again.

Responses

Musimap Web API returns all response data as a JSON object. A wrapper is always used such as the following:

{
    "status": 200,
    "timestamp": 1605612244215,
    "data": [
        ...
    ]
}

status will always reflect the response:

timestamp (in ms) defines when the query has been performed.

data contains the results related to your query.

Note: Depending on your query, other fields could be added such as size, offset, total_size,...

Error Response Schema

Unsuccessful responses return a JSON object containing the following information:

Key	Value Type	Description
status	integer	The HTTP status code that is also returned in the response header.
timestamp	integer	The timestamp, in ms.
error	string	The cause of the error.
message	string	A short description of the cause of the error.

{
    "status": 404,
    "timestamp": 1605613492829,
    "error": "Not Found",
    "message": "Organization Not Found"
}

Response Status Codes

Web API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

Code	Description
200	OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201	Created - The request has been fulfilled and resulted in a new resource being created.
204	No Content - The request has succeeded but returns no message body.
400	Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.
401	Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
404	Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
429	Too Many Requests - Rate limiting has been applied.
500	Internal Server Error. You should never receive this error because our clever coders catch them all... but if you are unlucky enough to get one, please report it to us.
502	Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503	Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Authentication

All requests to Web API require authentication. This is achieved by sending a valid OAuth access token in the request header:

curl --location --request GET 'https://api-v2.musimap.io/{YOUR_ENDPOINT}' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'