openwhyd

Openwhyd API

Openwhyd is a free and open-source music curation service that allows users to create playlists of music tracks from various streaming platforms (YouTube, SoundCloud, Vimeo, Deezer…) and to discover the music posted by other users.

Openwhyd Demo Video

It’s important for us that:

In order to satisfy these scenarios, we provide two APIs:

Openwhyd Data Export API

The goal of the Data Export API is to give free access to data that users publicly posted on Openwhyd.

This API can be used by anyone, without authentication, to download the list of tracks of:

The list of tracks can be downloaded in several formats:

Please use these URLs responsibly: add a reasonable delay between requests, in order to not put too much pressure on our server. Thank you!

GET Parameters

A list of tracks can be downloaded by appending the following HTTP GET parameters to Openwhyd URLs:

Examples

Examples:

If the links format was selected, Openwhyd will return a text document with one URL per posted track.

Example:

//soundcloud.com/deadoceans/mitski-your-best-american-girl-3#https://api.soundcloud.com/tracks/249475048
//youtube.com/watch?v=If8ChYjdFdE
//alexanderbrandon.bandcamp.com/track/sunrise-on-vanaar

These URLs are direct links to the track’s content, on their source platform. (e.g. YouTube, SoundCloud, etc…)

URLs are provided without protocol, but can be safely prefixed with https:.

Response format: json

If the json format was selected, Openwhyd will return a JSON array containing one object per posted track.

Example:

[
  {
    _id: '5c05b9675b1d901f32b6fe4b',
    uId: '4d94501d1f78ac091dbc9b4d',
    uNm: 'Adrien Joly',
    text: '',
    name: 'Mitski - Your Best American Girl',
    eId: '/sc/deadoceans/mitski-your-best-american-girl-3#https://api.soundcloud.com/tracks/249475048',
    img: 'https://i1.sndcdn.com/artworks-000149087394-z2wpob-t500x500.jpg',
    nbP: 6,
    nbR: 1,
    lov: [],
  },
  {
    _id: '5c0561f65b1d901f32b6fdf4',
    uId: '4d94501d1f78ac091dbc9b4d',
    uNm: 'Adrien Joly',
    text: 'merci @[Camille B](user:51483cad7e91c862b2ab6dc2) <3',
    name: 'The Posies, Burn & Shine',
    eId: '/yt/If8ChYjdFdE',
    ctx: 'bk',
    img: 'https://i.ytimg.com/vi/If8ChYjdFdE/default.jpg',
    src: {
      id: 'https://www.youtube.com/watch?v=If8ChYjdFdE',
      name: 'The Posies, Burn &amp; Shine - YouTube',
    },
    nbP: 8,
    lov: [],
  },
];

The eId property contains the unique identifier of the track/video on its source platform:

You will find a full list of supported source platforms with their identifier prefix in the Formats section of this document.

Openwhyd User API

The goal of the User API is to allow users to interact with their Openwhyd account from a 3rd-party software.

It can be used to read and update lists of tracks associated to the authenticated user.

In order to allow this, a session must be initiated on Openwhyd’s API, by providing the user’s email and password. When a session is initiated properly, a cookie will be returned. This cookie will be required for the following API requests. If you want to know more about the authentication flow, read login-flow.md.

Note: an API client for Node.js was written to handle the session-based authentication. It can be installed using npm install openwhyd-api-client.

In this section, we will document all the API endpoints supported by Openwhyd.

Table of contents:

User session / logging

LOGOUT

GET /login?action=logout

Clears openwhyd cookie (HTTP headers) and session (database)

Parameters: (GET or POST)

Returns:

FORGOT PASSWORD

GET /login?action=forgot&email

Sends a password reset URL to the user by email.

Parameters: (GET or POST)

Response: (HTML form or JSON, depends of the ajax parameter)

LOGIN WITH EMAIL

html : (GET /login?action=login&email&md5)

Initializes the user session and corresponding cookie, using provided credentials.

Can update the user’s Facebook access token in the database, if provided.

Parameters: (GET or POST)

Response: (HTML form or JSON, depends of the ajax parameter)

LOGIN WITH FACEBOOK

Initializes the user session and corresponding cookie (via Login API), using provided FB authorization.

Updates the user’s Facebook access token in the database.

html : (GET /facebookLogin?action=login&fbUid&fbAccessToken)

Parameters: (GET or POST)

Cookies: (initialized by facebook SDK, one of these must be set in the headers of the HTTP request)

Response: (JSON)

CONNECT FACEBOOK ACCOUNT TO OPENWHYD ACCOUNT

Enables:

This endpoint is called when a Openwhyd user (that is already logged in) clicks on a Facebook Connect button, and this Facebook account is not yet connected to another Openwhyd account.

html : (GET /facebookLogin/action=link&fbUid&fbAccessToken)

Parameters: (GET or POST)

Cookies: (initialized by facebook SDK, one of these must be set in the headers of the HTTP request)

Response: (None)

Register / sign up a new user

This endpoint is called from a sign up form.

If sign up succeeds, the user is logged in similarly to the /login endpoint: a session is set up in DB, and a cookie is returned in the HTTP header of the response.

POST /register...

Parameters:

Response: (JSON, if ajax parameter was set to true)

Get user data

GET /api/user

Parameters:

Response: (JSON)

*frequency is one of these values:

Set user data

POST /api/user

Updates one or more fields of the logged in user.

Allowed Parameters (one or many can be passed):

Response: (JSON)

SEARCH TRACKS POSTED BY OTHER USERS

Returns a list of 5 tracks posted by other users, matching the given full-text search query.

This endpoint is used on the “add track” dialog, to incentivize re-posting from other users.

html : (GET /search?context=addTrack&q=coco)

Parameters:

Response:

SEARCH TRACKS POSTED BY ME + OTHER USERS

Returns a list of tracks posted the logged in user, and by other users, matching the given full-text search query.

This endpoint is used on the experimental openwhyd.org/mobile page, as a compromise between looking up one’s own tracks and re-adding from others.

html : (GET /search?context=quick&q=coco)

Parameters:

Response: (JSON hierarchy)

Combined search page: posts + users + playlists

Returns a list of matching:

This endpoint is used for the openwhyd.org/search page.

html : (GET /search?q=coco)

Parameters:

Response: (JSON)

Subscriptions

List subscribers of a user

GET /api/follow/fetchFollowers/<id>

Parameters:

Response: JSON array of objects with the following fields:

List subscriptions of a user

GET /api/follow/fetchFollowing/<id>

Parameters:

Response: JSON array of objects with the following fields:

Get subscription status of a user

Subscribes or unsubscribes to a user. (must be logged in)

GET /api/follow?action=get&tId

Parameters:

Response: (two cases)

(Un)subscribe to a user

Subscribes or unsubscribes to a user. (must be logged in)

GET /api/follow?action&tId

Parameters:

Response:

TRACKS

POST TRACK / Edit a Post

GET /api/post?action=insert&...

Parameters:

Result: (JSON)

Examples:

Delete post

GET /api/post?action=delete&...

Parameters:

Return:

Like / unlike a post

GET /api/post?action=toggleLovePost&...

Parameters:

Return:

Likes Tracks by User

GET /[uId]/likes?format=json

Parameters:

Fetch list of users who liked a post

GET /api/post?action=lovers&...

Parameters:

Return: (JSON)

Fetch list of users who re-added a post

GET /api/post?action=reposts&...

Parameters:

Return: (JSON)

Log a play

To be called whenever a track effectively started or failed playing, for analytics and diagnosis.

GET /api/post?action= incrPlayCounter&...

Parameters:

Return:

Scrobble a play to Last.fm

To be called whenever a track ends playing, for users who connected their last.fm account.

GET /api/post?action= scrobble&...

Parameters:

Return: (JSON)

Add a comment to a post

GET /api/post?action=addComment&...

Parameters:

Return: (JSON)

Delete a comment from a post

GET /api/post?action=deleteComment&...

Parameters:

Return: (JSON)

LIST TRACKS POSTED BY USER

GET /:uHandle/[playlist/:playlistId] GET /u/:uId/[playlist/:playlistId]

Parameters:

Return:

Examples:

INCOMING STREAM (HOMEPAGE)

GET /[stream]

Parameters:

Return:

HOT TRACKS

GET /hot

Parameters:

Return:

Notes:

Detailed track info

GET /c/[postId]?format=json

Parameters:

Return:

Share a post to Openwhyd users (notification)

POST /api/post/<pId>/sendToUsers

User must be logged in => openwhyd session cookie must be included.

Parameters:

Return (JSON):

Playlists

Get playlist data

GET /api/playlist/<id>

GET /api/playlist?id=<id1>&id=<id2>

Parameters:

Returns: a JSON array of playlists containing the following fields:

Create a playlist

POST /api/playlist

Creates a playlist for the logged in user.

NB: it’s also possible to create a playlist while posting a track, by providing (create) as the value of the id field of the pl parameter.

Parameters:

Returns: (JSON)

Rename a playlist

POST /api/playlist

The user who created the provided playlist must be logged in (based on cookie) before using this endpoint

Parameters:

Returns: (JSON)

Delete a playlist

POST /api/playlist

Deletes a playlist and moves all the contained tracks in to the user’s default profile stream. (tracks will not be part of a playlist anymore)

The user who created the provided playlist must be logged in (based on cookie) before using this endpoint

Parameters:

Returns: (int) the number of the deleted playlist (as provided in the call)

Set track order of a playlist

POST /api/playlist

This call will set the order field of each post contained in the provided playlist from 1 to n, so that the are displayed in the desired order.

The user who created the provided playlist must be logged in (based on cookie) before using this endpoint.

Parameters:

Returns: (JSON)

Update the image of a playlist

POST /api/playlist

To be called after the image was uploaded to Openwhyd. Upon success, this uploaded image file will be moved to Openwhyd’s playlist images directory.

The user who created the provided playlist must be logged in (based on cookie) before using this endpoint

Parameters:

Returns: (JSON)

Share a playlist to Openwhyd users (notification)

POST /api/playlist

User must be logged in => openwhyd session cookie must be included.

Parameters:

Return (JSON):

Upload

Upload a file to Openwhyd’s file server

Uploading a file is necessary before changing any image associated (directly or not) to user-generated data (ex: user avatar, user profile banner, playlist cover, etc…). User must be logged in (based on attached cookie).

POST /upload

Example of use:

Parameters:

Triggers the following standard events:

Response: (JSON)

Delete an uploaded file

POST /upload

Parameters:

Formats and Appendix

Syntax of “eId” identifiers

The “eId” field contains the unique identifier of the track/video on its hosting source. (e.g. youtube/soundcloud/vimeo):

Syntax of a mention (in comment text)

sample comment: blah blah **@[Camille B](user:51483cad7e91c862b2ab6dc2)** blah blah...

syntax:

URLs for fetching images

Images can be fetched for any Openwhyd resource (tracks, user, playlists…) from a unified URL scheme, provided the id of this ressource.

The controller will either redirect to the external ressource (e.g. facebook avatars, hosted by facebook) or return the image directly. In the first case, HTTP GET parameters are passed through to the redirect URL.

URL templates:

Specific notes about the playlist template: