Protocol

Implementation

The Amper Music API is implemented as a set of RESTful HTTP/1.1 requests and responses. All requests must use HTTPS protocol on port 443.

In general, the API design follows the principles of the JSON API 1.0 specification.

Base URL

The base URL for all requests is api.ampermusic.com. All requests must include the header Host: api.ampermusic.com.

Cross-Origin Resource Sharing

The Amper API supports Cross-Origin Resource Sharing (CORS) using a whitelist approach. Third-party websites and applications having a business relationship with Amper Music are added to the whitelist as required.

To activate CORS behavior, the client must include an Origin request header set to an approved value. For preflight (i.e. OPTIONS) requests, the client must access a valid URL with a supported HTTP method for that URL in the Access-Control-Request-Method request header. Most web browsers perform these operations automatically, although client code may need to perform additional steps to leverage CORS fully for their use case.

Authentication

HTTP requests can use either Basic (preferred) or Bearer authentication. When a user issues a login request, the response includes a session token. This token must be used in the Authorization header for most of the other API requests.

Basic Authentication

Basic authentication uses the Authorization request header with the format Authorization: <username>:<password>, where <username>:<password> is Base64 encoded. Send a valid token as the HTTP username with a blank password. For example, for the token xyzzy, use the value eHl6enk6, which is the base64-encoded value for xyzzy: (note the trailing colon).

Example:

Authorization: Basic eHl6enk6

Bearer Authentication

Bearer authentication uses the Authorization request header with the format Authorization: Bearer <credentials>, where <credentials> is a valid token. Send the token as the <credentials>. For example, if the token is aabbcd, use the value aabbcd.

Example:

Authorization: Bearer aabbcd

ETags

All responses contain an ETag header representing the state of the resource on the server. PATCH, PUT, or DELETE requests to modify a resource must contain an If-Match header that matches the ETag of the resource on the server. If the ETags do not match, no modifications are made and a 412 Precondition Failed response is returned.

Example Request Header:

If-Match: 0123456789abcdefgh

Example Response Header:

ETag: 0123456789abcdefgh

Pagination

For GET requests that return a list of data records, you can specify the first record to return and the number of records to return using the offset, cursor, and limit query parameters. Responses return all records in “date created” order in ascending order.

Offset/Limit Mode

To specify the numeric offset of the the first data record returned, use the offset query parameter. Valid values are 1 to 1000. Use the limit query parameter to specify the number of data records to return. Valid values are 1 to 100. The limit parameter is optional and defaults to 10 if it is not specified. The maximum result accessible using Offset/Limit method is 1,100 (with offset=1000 and limit=100). To retrieve additional records, use the Cursor/Limit mode.

Example:

?offset=20&limit=5

Cursor/Limit Mode

To specify the cursor ID of the first data record returned, use the cursor query parameter. Use the limit query parameter to specify the number of records to return. Valid values are 1 to 100. The limit parameter is optional and defaults to 10 if it is not specified. All data records are accessible by iterating over the entire chain of cursor IDs.

Note: This design deviates from the JSON API specification, which prescribes namespaced query parameters. For example, page[offset] and page[limit].

Example:

?cursor=abcd1234&limit=5

Content Type

The content type for all requests and responses is application/vnd.api+json. Other content types are not supported.

Example:

Content-Type: application/vnd.api+json

Response Status Codes

The Amper platform returns the following response status codes:

Status Code Description
200 OK The request was successful. The object was found and returned
201 Created The object was successfully created. The message body contains its current state. If present, the Location header contains the URL for the new object
202 Accepted The request was successfully accepted. Further processing will be performed
204 No Content The request was successful. The response contains no content
400 Bad Request The system was unable to process the request because it was malformed
401 Unauthorized The request was unsuccessful because of an authentication failure
404 Not Found A path or ID specified in the URL does not exist. This code is also returned in cases where an object does exist in the system, but it does not belong to authenticated user
405 Method Not Allowed The requested method cannot be performed on the specified object
409 Conflict The object could not be created because it conflicts with an existing object. Ensure the user-defined project name is unique for the user
412 Precondition Failed An object could not be updated or deleted because the If-Match request header does not match the ETag of the resource on the server
415 Unsupported Media Type The Content-Type header is missing or set to an unsupported value. Ensure the Content-Type header is set to application/vnd.api+json
422 Unprocessable Entity A POST request was parsable, but failed a validation check. A required property was either missing or a value was invalid
429 Too Many Requests The request was rejected because too many similar requests have been submitted in a short amount of time. Wait and try submitting requests later