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. Please contact your sales representative if your require CORS for a client-side implementation.

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 100,000. 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 100,100 (with offset=100000 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

Sorting

Certain endpoints which return lists of objects can be sorted based on an attribute within the objects. This is accomplised by adding a ?sort= parameter to the query string, with a value corresponding to the name of the field or fields to sort on. Multiple fields may be specified by concatenating the names together with a comma (,) character.

By default, sorting is performed in ascending order. To reverse a sort, prepend a dash (-) character before an attribute name.

Example Sort Meaning
?sort=display_name Sort by display_name in ascending order.
?sort=-display_name Sort by display_name in descending order.
?sort=display_name,-date_create Sort by display_name in ascending order, and for any objects whose display_names compare equal, sort by date_create in descending order.

If multiple fields are provided, the ones listed first will be applied first, and subsequent fields will be used to resolve objects that compared equal based on earlier fields.

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