Beat Technology Core API Documentation (2.0.0)

• 1. End-user apps (customers)
  • Web frontend users (visitors, authenticated users)
  • Mobile app users (visitors, authenticated users)
  • STB users (visitors, authenticated users)
• 2. Backoffice app (support team)
• 3. Partner integrations (subscription management)

• Production environment: `https://api.{service-domain}/v2/{resource}`
• Staging: environment: `https://api.dev.{service-domain}/v2/{resource}`

Both Request and Response should be UTF-8 encoded.

id - string

This property uniquely identifies a resource. Every resource of a given kind will have a unique id. Even though an id may sometimes look like a number, it should always be treated as a string.

date - string

UTC. Complete date: YYYY-MM-DD (eg 1997-07-16)

datetime - string

UTC. Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30Z), compliant with http://www.w3.org/TR/NOTE-datetime.

Where:

• YYYY = four-digit year

• MM = two-digit month (01=January, etc.)
• DD = two-digit day of month (01 through 31)
• hh = two digits of hour (00 through 23) (am/pm NOT allowed)
• mm = two digits of minute (00 through 59)
• ss = two digits of second (00 through 59)
• TZD = time zone designator (Z ONLY)

NOTE:

1. no decimal fraction of a second
2. TZD is ''Z'' ONLY, no ''+hh:mm'' or ''-hh:mm''

url - string

• Fully specified urls only.

• Cover arts: `33, 50, 52, 75, 100, 175, 180, 182, 200, 350, 500* and 800* pixels` (* - Cover art at this size is not available for some releases)
• Artist pictures: `150, 200 and 300 pixels`.

• URL/URI - lower case, underscore.
• JSON parameters - lower case, underscore.

Content-Type

• `v2/oauth2` OAuth2 API:
  • `Content-Type: application/x-www-form-urlencoded` - see OAuth2 API spec for details
• `v2/*` API (all endpoints except `v2/oauth2`):
  • `Content-Type: application/json` - body of POST/PUT request and body of the response is JSON-encoded
  • **DO NOT USE** browser's default `Content-Type: application/x-www-form-urlencoded`.
  • Use for instance `JSON.stringify` function in JavaScript and always set the `Content-Type: application/json` header.

Pagination

Lists or search results are paginated. Pagination based on Range headers with custom range unit depends on resource.

Headers according to HTTP/1.1 RFC:

• 3.12 Range Units.
• 14.5 Accept-Ranges
• 14.16 Content-Range
• 14.35 Range

Defaults: \n * Offset: 0. \n * Max page size: 10, 20, 100, 200 or 1000 items.

Note inconsistency in RFC between formats:

Range: tracks=0-49 \n Content-Range: tracks 0-49/*

NOTES from RFC:

• Content-Range: unit SP (first-pos ''-'' last-pos) ''/'' (instance-length | ''*'')
• A server sending a response with status code 416 (Requested range not satisfiable) SHOULD include a Content-Range field with ''*''.
• A response with status code 206 (Partial Content) MUST NOT include a Content-Range field with ''*''.
• The instance-length specifies the current length of the selected resource (known number of accessible items in the collection).

IMPORTANT

• There is next range/page available if instance-length > last-pos + 1.
• There is no next range/page available (last page reached) if instance-length >= last-pos + 1.
• Actual number of items in the response can be less than announced by Content-Range fields: (last-pos - first-pos + 1). Example: the result can contain less than 20 tracks even if Content-Range is 40-59. Each result page can contain just part of requested range, but Content-Range header is always represents full range (correct case: request with Range 30-59 >> 2 tracks in response body + Content-Range 30-59/60).

Examples:

// first search query = get first 20 tracks (20 is default value)
// NOTE: the result can contain less than 20 tracks even if Content-Range is 0-19.

Request:
  GET /v2/tracks?query=gaga
  
Response:
  206 Partial Content
  Accept-Ranges: tracks
  Content-Range: tracks 0-19/21 // 21>19+1 => next page exists
  { \n \t\t \"tracks\": [{},{},...] \n \t }

// get second 20 tracks (20-39 - inclusive)
// NOTE: the result can contain less than 20 tracks even if Content-Range is 20-39.

Request:
  GET /v2/tracks?query=gaga
  Range: tracks=20-39
  
Response:
  206 Partial Content \n \t Accept-Ranges: tracks \n\t Content-Range: tracks 20-39/41 // 41>39+1 => next page exists \n\t {...}

// get third 20 tracks (40-59 - inclusive)
// NOTE: the result can contain less than 20 tracks even if Content-Range is 40-59.

Request:
  GET /v2/tracks?query=gaga
  Range: tracks=40-59

Response:
  206 Partial Content
  Accept-Ranges: tracks
  Content-Range: tracks 40-59/61 // 61>59+1 => next page exists \n\t {...}

// error: invalid range

Request:
  GET /v2/tracks?query=gaga
    Range: tracks=1000-999
    
    Response:
      416 Requested Range Not Satisfiable
    {}

Custom HTTP headers

• [DEPRECATED] X-User-Id (optional) Beat User ID. MUST be included into each authenticated request to Beat API on behalf of end user. Needed for request routing, but not for authentication.
• [DEPRECATED] X-Client-Id (optional) Header can be used for request routing as well as for providing client-specific data. Header should be included into each request.
• X-Country (optional) Some data (products, catalog metadata) can be country-specific, client may provide country code in the header. Format: a two-letter code according to (ISO 3166-1 alpha-2)[https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]
• X-Include (optional) Specify which additional sub-objects to include in aresponse. The value is a comma-separated list of object names. Valid names are: release-reviews, release-tracks, release-notes, release-prices, track-prices, group-releases, group-banners
• X-Release-Cover-Sizes (optional) Header specifies sizes for Release cover basic objects. See Basic response objects section for details.
• X-Artist-Image-Sizes (optional) Header specifies sizes for Artist image basic objects. See Basic response objects section for details.
• X-Actor-Image-Sizes (optional) Header specifies sizes for Actor image objects. See Basic response objects section for details.
• [DEPRECATED] X-Audio-Formats deprecated in favour of X-Stream-Formats
• X-Stream-Formats (optional) Header specifies stream quality. See v2/streams/online and v2/streams/offline for details. The value is a comma-separated list of object names. Valid names are: */high, */normal, */low, h264/*.
• X-Shop (optional) A shop is a named group of catalog metadata, mainly releases and tracks. Several endpoints support filtering on shops. In this case, if a a shop filter is specified, the entity is only returned if the release is actually a member of that shop – otherwise, 404 is returned. If a shop is not specified, the entity can always be returned as long as it has not been taken down OR it falls back to default shop. Default shop and list of supported shops are service specific. Special value X-Shop: all specifies not filtering on shops at all and not using the default shop.

Response body is JSON-encoded.

Format conventions

Root object of response is a namespace for keys (always a hash, not an array):

{tracks:[{track:{...}}, {track:{...}}]} // no
{tracks:[{...}, {...}]} // yes
{title: 'value'} // no \n {track: {title:'value'}} // yes

HTTP error codes

• 400 Bad Request - Invalid input parameter. Error message should indicate which one and why.
• 401 Unauthorized - Bad or expired token. This can happen if the user or Beat revoked or expired an access token. To fix, you should re-authenticate the user.
• 403 Forbidden - Bad OAuth request. Check request signature, timestamp, etc.
• 404 Not Found - Requested resource/object is not exists.
• 405 Method Not Allowed - Request method not expected (generally should be GET or POST).
• 5xx Server error. Check status page or report a bug.

Error response example

{
  "error": "exception", // required
  "error_description": {string}, // required
  "error_developer": {object} // optional
}

[TODO] Partial response (reserved for future)

By default, the server sends back the full representation of a resource after processing requests. For better performance, you can ask the server to send only the fields you really need and get a partial response instead.

Format of fields parameter based on XPath syntax.

Example request:

1) Option (preferred)
  GET /v2/releases \n\t X-Fields: id,tracks(id,title,covers,artist/cover)

2) Option
  GET /v2/releases?fields=id,tracks(id,title,covers,artist/cover) \n\t NOTE: fields - must be URL encoded

HTTP 400 Bad Request - if fields query parameter is invalid

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -i https://api.beat.no -H \"Origin: http://example.com\"
HTTP/1.1 302 Found \n Location: https://developer.beat.no

Any domain that is registered as an OAuth Application is accepted. Here’s a sample request for a browser hitting beat.no web app:

$ curl -i https://api.beat.no -H \"Origin: http://beat.no\"
HTTP/1.1 302 Found
Location: https://developer.beat.no
Access-Control-Allow-Origin: http://beat.no
Access-Control-Expose-Headers: Content-Range, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

$ curl -i https://api.beat.no -H \"Origin: http://beat.no\" -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://beat.no
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, X-Release-Cover-Sizes, X-Artist-Image-Sizes, X-Stream-Formats, Authorization, X-User-Id, Range
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: Content-Range, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

Authorization flow example

Authorization is based on OAuth2. Every request must include Authorization header.

POST /v2/someresource
Authorization: Bearer <access-token> // required, example: 5aa5cf3e75fb05b1400a024e2e748b40320a4ae8

Activation flow example

• GET /v2/users?msisdn=4742424242
• POST /v2/users -> user_id
• POST /v2/users/:user_id/migrations + {product_id=13} -> sub_id

Deactivation flow example

• GET /v2/users?msisdn=4742424242
• GET /v2/users/:user_id/subscriptions?product_id=13
• DELETE /v2/users/:user_id/subscriptions/:sub_id

Get access token

>>>
POST /v2/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=APP_ID
&client_secret=APP_SECRET

<<<
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "expires_in":3600,
  "token_type":"bearer",
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" // optional
}

Following requests to API resources should include Authorization header.

POST v2/resource
Authorization: Bearer <access-token>

>>>
GET /v2/products

<<<
206 Partial Content
{
  "products": [{Product}]
}

>>>>
POST /v2/users
{
  "msisdn": {string}, // optional
  "firstname": {string}, // optional
  "lastname": {string}, // optional
  "email": {string}, // optional
}

<<<<
409 Conflict - if msisdn is already registered
{}

201 Created
{
  "user": {User}
}

>>>
POST /v2/users/:user_id/migrations
{
  "product_id": {string},
  "renewable": {boolean} // optional, defaults to true, whether new subscription should renew or not
}

<<<<
201 Created // success, activated
{}

>>>
GET /v2/users/:user_id/subscriptions

<<<
206 Partial Content
{
  "subscriptions": [{Subscription}]
}

>>>
PATCH /v2/users/:user_id/subscriptions/:subscription_id
{
  "state": {int}
}

<<<
200 OK // success
{
  "subscription": {
      "expiry_date": {datetime|null},
      "next_billing_date": {datetime|null},
      "state": {int}
      ...
  }
}

Use one of the following state values:

• pass 3 to resume stopped subscription
• pass 6 to stop subscription, it will expire in the end of period

>>>
DELETE v2/users/:user_id/subscriptions/:subscription_id

<<<
200 OK // success, deactivated
{}

Operations around actors

Operations around artists

API implements OAuth 2.0 protocol for authentication.

Each request to API resources requires an access_token. There are a few ways to get access token depending on client type.

Mobile Apps or Web Apps use authentication by username/password.

Access Tokens

• User Access Token - token associated with user id - can be requested by:
  • `grant_type=password`
  • `grant_type=clone_token`
  • `grant_type=signed_msisdn`
  • `grant_type=coupon`
  • `grant_type=verification_code`
  • `grant_type=account_user`
  • `grant_type=openid_handle`
• App Access Token can be requested by:
• `grant_type=client_credentials`

User Tokens

IMPORTANT. The duration of access_token, refresh_token, scope is unspecified and can be changed at any time. So clients have to expect any duration at any moment in the future (i.e. data type should be considered as a TEXT in terms of SQL).

Authentication by User Password (grant_type=password)

Flow: 4.3 Resource Owner Password Credentials Grant.

NOTE: Authentication by user password is an exceptional case and such flow should only be enabled for selected applications. All other the third-party applications MUST use another ways described below.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=password
  &username=<msisdn|email>
  &password=<password>
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "" // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWI\", // optional
    "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

Authentication by Signed MSISDN (grant_type=signed_msisdn)

Issue new access token based on signed MSISDN. Used to support Web App's passwordless login for Gakk Media (Robi Web App and others).

SECURITY NOTE: Enabled for Bangladesh phone numbers only at the moment. SECURITY NOTE: Signature can only be generated by nginx based on specific authorization headers provided by carrier's networks. It makes possible to login to the app without typing of password. See nginx configuration for signature generation procedure.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=signed_msisdn
  &msisdn=8801600000199
  &msisdn_signature=87r1uhasdyfp13jskfd
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

[DEPRECATED] Authentication by coupon code (grant_type=coupon)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=coupon
  &code=test1
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

Authentication by verification code (grant_type=verification_code)

Code can be generated and optionally send to customer by POST v2/codes.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=verification_code
  &msisdn=0029133437595305 // optional, one of msisdn or user_id should present
  &user_id=1111 // optional, one of msisdn or user_id should present
  &code=1234
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

Cross-client Authentication (grant_type=clone_token)

Clone user token for the usage by the new client.

The grant_type=clone_token can be used to issue new access_token for the new client based on access_token issued by the different client (both clients are from the same project). The new issued access_token will always have the same associated user_id.

NOTE: Use grant_type=refresh_token to issue access_token for the same client.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=clone_token
  &access_token=2YotnFZFEjr1zCsicMWpAA // access token issued with another client credentials from the same project
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET

Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"087fashf34h7adysfy", // new token with the same user_id
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "" // optional
    "refresh_token":"dfq4lajw78152345sfga", // optional
    "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

Switching between account users (profiles) (grant_type=account_user)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=account_user
  &access_token=<access_token> // access token of one of account users (profiles)
  &user_id=<target_user_id> // id of target profile-user within the same account
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"087fashf34h7adysfy", // new token with the same user_id
  "expires_in":3600,
  "token_type":"example", // bearer
  "scope": "" // optional
  "refresh_token":"dfq4lajw78152345sfga", // optional
  "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
}

Authentication by OpenID auth session handle (grant_type=openid_handle)

This option is used to authenticate by a previously-started OpenID session. The handle is a value that retrieved during the first step of this process. Use this call only after the OpenID callback is finished.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=openid_handle
  &handle=<handle>
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "" // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", // optional\_
    "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

TODO

• Third-party Native Apps Flow: 4.1. Authorization Code Grant \n - Third-party Web Apps Flow: 4.2. Implicit Grant

App Tokens

App tokens are used to make requirests to Beat APIs on behalf of an app rather than a user. This can be useful to provide "visitor mode" in the apps.

Authentication by Client Credentials (grant_type=client_credentials)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=client_credentials
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response (the same as for grant_type=password):
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "", // optional
    // NOTE: no refresh_token field
  }

Refreshing Tokens (grant_type=refresh_token)

Access tokens have a limited lifetime and can be refreshed when required without asking the user to login again to get new token.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=refresh_token
  &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET

Response (the same as for grant_type=password):
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "", // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" // optional
  }

Install Referrer support

Introduced mainly to support Google Play Install Referrer API.

There is an optional parameter to help tracking of install events. When user logs in to the app, client app may specify install_referrer string param provided by Google Play services.

IMPORTANT FOR CLIENTS: App should add install_referrer param only once and must clean it on after successful log in, so repeated log ins should not be tracked/rewarded.

Example:

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=password
  &username=johndoe
  &password=A3ddj3w
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET,
  &install_referrer=u_12345
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "expires_in":3600,
      "token_type":"example", // bearer
      "scope": "" // optional
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", // optional
      "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

Operations around banners