Skip to content

Instantly share code, notes, and snippets.

@kevcha

kevcha/doc.md

Last active August 29, 2015 14:13
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save kevcha/afe6d905569a705e921e to your computer and use it in GitHub Desktop.
Save kevcha/afe6d905569a705e921e to your computer and use it in GitHub Desktop.
Download ZIP
1D touch API documentation
Raw
doc.md

Authentication

Get an OAuth Token

Each user that has a valid 1D touch account can generate an api Token with

POST /oauth/token
{
  grant_type=password
  username=user@example.com
  password=password
}

This can be done using curl with

curl -F grant_type=password \
-F username=user@example.com \
-F password=passhash \
-X POST https://music.1dtouch.com/oauth/token

The API response would be :

{
  "access_token": "2f931896365950b210bae7db8c65ccf0ecd0f53320a9cd97bbb4a2168d99176e",
  "token_type": "bearer",
  "created_at": 1421691018
}

You need to save this token on your side and be sure to keep it private. This token make us able to identify corresponding user, and it should be set in headers for all requests.

Example of request with token :

Headers:
Authorization: Bearer 2f931896365950b210bae7db8c65ccf0ecd0f53320a9cd97bbb4a2168d99176e

GET /api/v1/albums

Destroy a token

You can destroy a user's token with :

Headers:
Authorization: Bearer 2f931896365950b210bae7db8c65ccf0ecd0f53320a9cd97bbb4a2168d99176e

POST /oauth/revoke
{
  token: "#{token_to_revoke}"
}

Note : You need to have a valid token to revoke another (or same) one

This can be done using curl with :

curl -F token= 9802ebeec3f9e146c646e360346dd302773d43bdb001c26fa8a34d543bf86f22 \
-H "Authorization: Bearer 9802ebeec3f9e146c646e360346dd302773d43bdb001c26fa8a34d543bf86f22" \
-X POST localhost:3000/oauth/revoke

API Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

curl 'https://music.1dtouch.com/api/v1/albums?page=2&per_page=100'

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination info is included in the Link header in the response.

Link:
<https://music.1dtouch.com/api/v1/albums?page=1&per_page=20>; rel="first",
<https://music.1dtouch.com/api/v1/albums?page=4&per_page=20>; rel="prev",
<https://music.1dtouch.com/api/v1/albums?page=6&per_page=20>; rel="next",
<https://music.1dtouch.com/api/v1/albums?page=54&per_page=20>; rel="last",

The possible rel values are:

Name Description
next Shows the URL of the immediate next page of results.
last Shows the URL of the last page of results.
first Shows the URL of the first page of results.
prev Shows the URL of the immediate previous page of results.

API Endpoints

Some changes can happen for some of those endpoints. We'll update this document on every change.

Albums

Get all albums

GET /api/v1/albums

Returns an array albums :

[
  {
    "id": 273,
    "icpn": "3700551766741",
    "title": "Mahler: Symphonie No. 5",
    "genres": [
      "Musique Classique : Musique Symphonique"
    ],
    "released_at": "2014-10-29",
    "cover": {
      "small_url": "https://commondatastorage.googleapis.com/music-staging/cargo/small_3700551766741.jpg",
      "medium_url": "https://commondatastorage.googleapis.com/music-staging/cargo/medium_3700551766741.jpg",
      "large_url": "https://commondatastorage.googleapis.com/music-staging/cargo/large_3700551766741.jpg"
    },
    "artists": [
      {
        "id": 914,
        "name": "Royal Concertgebouw Orchestra"
      },
      {
        "id": 913,
        "name": "Rafael Kubelik"
      }
    ],
    "label": {
      "id": 212,
      "name": "Les Indispensables de Diapason"
    },
    "tracks": [
      {
        "id": 3272,
        "isrc": "FR9W15100085",
        "title": "Symphony No. 5: V. Rondo-Finale. Allegro - Allegro giocoso. Frisch.",
        "duration": "PT00H14M43S",
        "genres": [],
        "disc_number": 1,
        "track_number": 4,
        "explicit": false,
        "high_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_320k.mp3",
        "low_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_192k.mp3",
        "available_territories": ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX",
          "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW",
          "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY",
          "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR",
          "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK",
          "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE",
          "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV",
          "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV",
          "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF",
          "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC",
          "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD",
          "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ",
          "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"
        ]
      }
    ]
  }
]

Get one album

GET /api/v1/album/:id

Returns corresponding album :

{
  "id": 273,
  "icpn": "3700551766741",
  "title": "Mahler: Symphonie No. 5",
  "genres": [
    "Musique Classique : Musique Symphonique"
  ],
  "released_at": "2014-10-29",
  "cover": {
    "small_url": "https://commondatastorage.googleapis.com/music-staging/cargo/small_3700551766741.jpg",
    "medium_url": "https://commondatastorage.googleapis.com/music-staging/cargo/medium_3700551766741.jpg",
    "large_url": "https://commondatastorage.googleapis.com/music-staging/cargo/large_3700551766741.jpg"
  },
  "artists": [
    {
      "id": 914,
      "name": "Royal Concertgebouw Orchestra"
    },
    {
      "id": 913,
      "name": "Rafael Kubelik"
    }
  ],
  "label": {
    "id": 212,
    "name": "Les Indispensables de Diapason"
  },
  "tracks": [
    {
      "id": 3272,
      "isrc": "FR9W15100085",
      "title": "Symphony No. 5: V. Rondo-Finale. Allegro - Allegro giocoso. Frisch.",
      "duration": "PT00H14M43S",
      "genres": [],
      "disc_number": 1,
      "track_number": 4,
      "explicit": false,
      "high_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_320k.mp3",
      "low_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_192k.mp3",
      "available_territories": ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX",
        "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW",
        "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY",
        "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR",
        "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK",
        "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE",
        "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV",
        "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV",
        "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF",
        "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC",
        "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD",
        "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ",
        "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"
      ]
    }
  ]
}

Artists

Get all artists

GET /api/v1/artists

Returns an array of artists :

[
  {
    "id": 544,
    "name": "1902"
  },
  {
    "id": 399,
    "name": "20syl"
  },
  {
    "id": 610,
    "name": "2 Good Souls"
  }
]

Get one artist

GET /api/v1/artists/:id

Returns corresponding artist :

{
  "id": 544,
  "name": "1902"
}

Labels

Get all labels

GET /api/v1/labels

Returns an array of first 25 labels :

[
  {
    "id": 129,
    "name": "1-800-Dinosaur"
  },
  {
    "id": 184,
    "name": "2.4.7. Films"
  },
  {
    "id": 39,
    "name": "25 Hour Convenience Store"
  }
]

Get one label

GET /api/v1/labels/:id

Returns one label :

{
  "id": 129,
  "name": "1-800-Dinosaur"
}

Tracks

Get one track

GET /api/v1/tracks/:id

Returns one track :

{
  "id": 3272,
  "isrc": "FR9W15100085",
  "title": "Symphony No. 5: V. Rondo-Finale. Allegro - Allegro giocoso. Frisch.",
  "duration": "PT00H14M43S",
  "genres": [],
  "disc_number": 1,
  "track_number": 4,
  "explicit": false,
  "high_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_320k.mp3",
  "low_bitrate_url": "https://commondatastorage.googleapis.com/music-staging/cargo/fr9w15100085_192k.mp3",
  "available_territories": ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX",
    "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW",
    "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY",
    "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR",
    "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK",
    "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE",
    "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV",
    "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV",
    "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF",
    "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC",
    "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD",
    "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ",
    "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"
  ],
  "cover": {
    "small_url": "https://commondatastorage.googleapis.com/music-staging/cargo/small_3700551766741.jpg",
    "medium_url": "https://commondatastorage.googleapis.com/music-staging/cargo/medium_3700551766741.jpg",
    "large_url": "https://commondatastorage.googleapis.com/music-staging/cargo/large_3700551766741.jpg"
  }
}

For some track, high_bitrate_url and low_bitrate_url are set to null. This means that we don't have the rights to stream those songs, so urls won't be given.

Listenings

Get yesterday's listenings

GET /api/v1/listenings

Returns :

[
  {
    "id": 1,
    "track_id": 5,
    "track_isrc": "USMC31477075",
    "three_seconds": true,
    "thirty_seconds": false,
    "fifty_percents": false,
    "ninety_five_percents": false,
    "distributor": {
      "id": 1,
      "name": "Believe"
    },
    "label": {
      "id": 1,
      "name": "SnapShot",
      "url": "http://localhost:7000/api/v1/labels/1"
    },
    "album": {
      "id": 1,
      "title": "Neil Diamond's Christmas Classics",
      "url": "http://localhost:7000/api/v1/albums/1"
    },
    "artists": [
      {
        "id": 1,
        "name": "Neil Diamond",
        "url": "http://localhost:7000/api/v1/artists/1"
      }
    ],
    "user": {
      "id": 1,
      "name": "Kévin Chavanne",
      "station": {
        "id": 1,
        "name": "BM Lyon"
      }
    }
  },
  {
    "id": 2,
    "track_id": 2746,
    "track_isrc": "FRT091000039",
    "three_seconds": true,
    "thirty_seconds": false,
    "fifty_percents": false,
    "ninety_five_percents": false,
    "distributor": {
      "id": 2,
      "name": "Idol"
    },
    "label": {
      "id": 192,
      "name": "Agoria Music",
      "url": "http://localhost:7000/api/v1/labels/192"
    },
    "album": {
      "id": 259,
      "title": "Grande Torino - EP",
      "url": "http://localhost:7000/api/v1/albums/259"
    },
    "artists": [
      {
        "id": 815,
        "name": "Agoria",
        "url": "http://localhost:7000/api/v1/artists/815"
      }
    ],
    "user": {
      "id": 1,
      "name": "Kévin Chavanne",
      "station": {
        "id": 1,
        "name": "BM Lyon"
      }
    }
  }
]

Get listenings for a custom date range

GET /api/v1/listenings?since=2015-01-26&until=2015-01-27

You must use ?since and &until url params to specify which date range you want to get listenings for. Given dates should respect YYYY-MM-DD format.

Deliveries

Get yesterday's deliveries

GET /api/v1/deliveries

Returns all deliveries that has been processed yesterday :

[
  {
    "id": 158,
    "created_at": "2015-02-06T16:38:07Z",
    "updated_at": "2015-02-06T19:54:37Z",
    "finished_at": "2015-02-06T19:54:37Z",
    "type": "new",
    "album": {
      "id": 142,
      "url": "http://music.1dtouch.com/api/v1/albums/142"
    }
  },
  {
    "id": 159,
    "created_at": "2015-02-06T16:38:08Z",
    "updated_at": "2015-02-06T19:56:21Z",
    "finished_at": "2015-02-06T19:56:21Z",
    "type": "update",
    "album": {
      "id": 93,
      "url": "http://music.1dtouch.com/api/v1/albums/93"
    }
  }
]

The type field is here to indicate if this delivery results in a new album or updates an existing album

Get deliveries for a custom date range

GET /api/v1/deliveries?since=2015-01-26&until=2015-01-27

You must use ?since and &until url params to specify which date range you want to get deliveries for. Given dates should respect YYYY-MM-DD format.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment