Request format

Access to the services provided by 7digital will be provided through a REST interface.

 

A typical request (excl. authentication) will look as follows:

 

http://api.7digital.com/1.0/artist/details?artistId=1

 

Response format

Standard responses will be returned in XML format.

 

A successful response will have the following format:

 

<response status="ok" version="1.0">

      <response content>

</response>

 

 

Response status equal error means an error has occurred whilst processing a request.

A failed request will instead of the results content contain an error message element:

 

<response status="error" version="1.0">
    <error code="1001">
        <errorMessage>Missing release or artist ID</errorMessage>
    </error>
</response>

 

Erorr codes can be split into following categories:

 

1XXX-   input parameters missing or invalid (e.g. string supplied where number expected)

2XXX-   parameter not matching 7digital data (e.g. non-existent productid supplied)

7XXX-   internal 7digital error (e.g. DB server connectivity problem)

 

Non XML responses

Requests to some special methods will return instead of XML response a client redirect (e.g. basket/checkout) or serve a media file (e.g. track/streampreview)

 

Authentication

Access to the 7digital API is controlled by a consumer key which needs to be supplied with every request. Keys are issued upon request, to obtain one please apply here.
 

Some API methods might also require requests to be signed using OAuth authentication protocol as described in OAuth Consumer Request 1.0 Draft 1. This will be clearely stated in the method description.
 

 

OAuth signed API requests will include the following parameters:

 

oauth_consumer_key – a static value identifying Xxxxxxx’s requests

oauth_nonce – a random string uniquely generated for each request

oauth_timestamp – timepstamp of the request (number of seconds since Jan 1 1970 0:00:00 GMT)

oauth_signature_method – signature method used to sign the request (currently only HMAC-SHA1 supported)

oauth_signature – generated from the service url and all the parameter name/value pairs of the request (inc. other oauth params) using the oauth_consumer_secret assigned to Xxxxxxx’s oauth_consumer_key

 

In addition to the above oauth_token parameter is required for requests accessing user specific resources. A unique oauth_token along with oauth_token_secret will be issued by 7digital for each user upon calling the login method for that user.

 

In case a request won’t successfully authenticate instead of the usual XML response one of the following standard HTTP error responses will be returned:

 

HTTP 400 Bad Request

• Unsupported parameter
• Unsupported signature method
• Missing required parameter
• Duplicated OAuth Protocol Parameter

HTTP 401 Unauthorized

• Invalid Consumer Key
• Invalid / expired Token
• Invalid signature
• Invalid / used nonce

 

Countries & currencies

7digital download stores are available in several countries across the world. In order to be able to provide users with the maximum possible amount of content available in their country and display prices in their local currency whenever possible all API methods accept a special prameter country. This parameter expects 2 letter ISO country code (eg. GB, US, DE). If country code is not supplied all operations will be actioned on the default store - currently the UK one.

Commercial customers who have a dedicated shop with custom content set up should instead of country code use parameter shopId set to the id assigned to them. Please contact our bussiness department to enquire about this option.

 

Lists & paging
 

All API methods that return a list of items in the response accept the following paging parameters:

 

page	Int	optional	Page number of the result set. If not supplied defaults to 1
pageSize	Int	optional	Number of items to be returned per page. If not supplied defaults to 10

 

Paging information will also be included in the response as per the format bellow:

 

<page>1</page>
<itemsPerPage>10</itemsPerPage>
<totalItems>21</totalItems>

Please contact us below for access to the full API documentation