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}'