CODEWITHSUNDEEP
rest
Dan Cauley
Dan Cauley

Reputation: 198

What is a restful way to implement this proposed API?

So I'm trying to develop a music player for my office with a restful API. In a nutshell, the API will be able to download music from youtube and load it into the current playlist of a running MPD instance. I also want to be able to control playback / volume with the API

Here's kind of what I was thinking so far:

Endpoint: /queue
    Methods:
        GET: Gets the current MPD playlist
        POST: Accepts JSON with these arguments:
           source-type: specify the type of the source of the music (usually youtube, but i might want to expand later to support pulling from soundcloud, etc)
           source-desc: Used in conjunction with source-type, ie, if source-type were youtube, this would be a youtube search query
           It would use these arguments to go out and find the song you want and put it in the queue
        DELETE: Would clear the queue

Endpoint: /playbackcontrol
    Methods:
        GET: Returns volume, whether playing, paused, or stopped, etc
        POST: Accepts JSON with these arguments:
            operation: describe the operation you want (ie, next, previous, volume adjust)
            optional_value: value for operations that need a value (like volume)

So that's basically what I'm thinking right now. I know this is really high level, I just wanted to get some input to see if I'm on the right track. Does this look like an acceptable way to implement such an API?

Upvotes: 3

Views: 454

Answers (2)

inf3rno
inf3rno

Reputation: 26139

I would use the following 2 main modules:

playlist/{trackId}
    source
    index
player
    playing
    track
    time
    volume

Playlist:

  • adding a track: POST playlist {source: ...}
  • removing a track: DELETE playlist/{id}
  • ordering tracks: PUT playlist/{id}/index 123
  • get track list: GET playlist

Player:

  • loading a track: PUT player/track {id: 123}
  • rewind a track: PUT player/time 0
  • stop the player: PUT player/playing false
  • start the player: PUT player/playing true
  • adjust volume: PUT player/volume .95
  • get current status: GET player

Ofc you should use the proper RDF vocab for link relations and for describing your data. You can find it probably here.

Upvotes: 1

Vasiliy Faronov
Vasiliy Faronov

Reputation: 12310

DELETE to clear the queue is not cool. PUT an empty queue representation instead. This will also come in handy later when you want to be able to rearrange items in the queue, remove them one by one etc.—you can GET the current queue, apply changes and PUT it back.

Volume is clearly better modeled as a separate /status/volume resource with GET and PUT. Maybe PATCH if you absolutely need distinct “volume up” and “volume down” operations (that is, if your client will not be keeping track of current volume).

Ditto for the playing/paused/stopped status: GET/PUT /status/playback.

To seed the client with the current status, make GET /status respond with a summary of what’s going on: current track, volume, playing/paused.

Upvotes: 2

Related Questions