REST API - project-owner/Peppy.doc GitHub Wiki
The REST API enables creation of the alternative GUIs (rich and web) for the Peppy Player. That also enables the access to the player from a command line (e.g. using curl).
Player Information
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| about | GET | http://localhost:8000/api/about | JSON | Information about current release name and date |
| newrelease | GET | http://localhost:8000/api/newrelease | JSON | Information about release name and date in Github |
| modes | GET | http://localhost:8000/api/modes | JSON | List of enabled modes |
| mode | GET | http://localhost:8000/api/mode | JSON | Get current mode |
| mode | PUT | http://localhost:8000/api/mode Request body: {"mode":"radio"} | Set current mode |
Resources
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| icon | GET | http://localhost:8000/icon/home.svg | SVG or PNG | GUI icon |
| flag | GET | http://localhost:8000/flag/Czech/flag.png | PNG | Flag image |
| backgrounds | GET | http://localhost:8000/backgrounds/bgr-1.jpg | JPG | Background image |
| fonts | GET | http://localhost:8000/fonts | JSON | List of available fonts |
| font | GET | http://localhost:8000/font/FiraSans.ttf | TTF font | GUI font |
| parameters | GET | http://localhost:8000/parameters | JSON | Configuration parameters |
| savers | GET | http://localhost:8000/savers | JSON | Screensavers configuration |
| labels | GET | http://localhost:8000/labels?language=English-USA | JSON | Localized labels |
| timezone | GET | http://localhost:8000/timezone | Text | Current timezone |
| log | GET | http://localhost:8000/log | Text | Log file |
| languages | GET | http://localhost:8000/api/languages | JSON | List of enabled languages |
| language | GET | http://localhost:8000/api/language | JSON | Get current language |
| language | PUT | http://localhost:8000/api/language Request body: {"language.name":"German"} | Set current language |
Playlists
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| playlist | GET | http://localhost:8000/api/playlist | JSON | Get Current Radio playlist |
| podcasts | GET | http://localhost:8000/podcasts | Text | Get Podcast playlist |
| podcasts | PUT | http://localhost:8000/podcasts Request body: Text | Save Podcast playlist | |
| streams | GET | http://localhost:8000/streams | Text | Get Streams playlist |
| streams | PUT | http://localhost:8000/streams Request body: Text | Save Streams playlist | |
| yastreams | GET | http://localhost:8000/yastreams | Text | Get YA Streams playlist |
| yastreams | PUT | http://localhost:8000/yastreams Request body: Text | Save YA Streams playlist | |
| jukebox | GET | http://localhost:8000/jukebox | Text | Get Jukebox playlist |
| jukebox | PUT | http://localhost:8000/jukebox Request body: Text | Save Jukebox playlist |
Lifecycle Commands
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| ping | GET | http://localhost:8000/command/ping | "success" | Ping command |
| reboot | POST | http://localhost:8000/command/reboot | Reboot player | |
| shutdown | POST | http://localhost:8000/command/shutdown | Immediate shutdown | |
| shutdown | GET | http://localhost:8000/api/shutdown | JSON | Get shutdown state |
| shutdown | PUT | http://localhost:8000/api/shutdown | Activate shutdown | |
| shutdown | DELETE | http://localhost:8000/api/shutdown | Deactivate shutdown |
Screensavers
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| screensavers | GET | http://localhost:8000/api/screensavers | JSON | List of available screensavers |
| screensaver | GET | http://localhost:8000/api/screensaver | JSON | Get current screensaver |
| screensaver | PUT | http://localhost:8000/api/screensaver Request body: {"screensaver.name": "slideshow"} | Set current screensaver | |
| screensaver | POST | http://localhost:8000/api/screensaver/start | Start screensaver | |
| screensaver | POST | http://localhost:8000/api/screensaver/stop | Stop screensaver |
Player
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| playpause | GET | http://localhost:8000/api/playpause | JSON | Get play/pause state |
| playpause | PUT | http://localhost:8000/api/playpause | Toggle Play/Pause state | |
| next | PUT | http://localhost:8000/api/next | Switch to the next station/track | |
| previous | PUT | http://localhost:8000/api/previous | Switch to the previous station/track | |
| title | GET | http://localhost:8000/api/title | JSON | Get current track/station name |
| image | GET | http://localhost:8000/api/image | PNG | The current player image (cover art) |
Volume & Equalizer
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| volume | GET | http://localhost:8000/api/volume | JSON | Get volume level |
| volume | PUT | http://localhost:8000/api/volume Request body: {"volume":20} | Set volume level | |
| mute | GET | http://localhost:8000/api/mute | JSON | Get mute state |
| mute | PUT | http://localhost:8000/api/mute | Toggle mute/unmute state | |
| equalizer | GET | http://localhost:8000/api/equalizer | JSON | Get equalizer state |
| equalizer | PUT | http://localhost:8000/api/equalizer | Set equalizer state |
Radio Player
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| radioplayer | GET | http://localhost:8000/api/radioplayer | JSON | Get the current state of the radio player |
| radioplayer | PUT | http://localhost:8000/api/radioplayer | Set the new player state | |
| genres | GET | http://localhost:8000/api/genres | JSON | Get genres |
| genre | GET | http://localhost:8000/api/genres | Text | Get the current genre |
| genre | PUT | http://localhost:8000/api/genres Request body: {"genre":"Rock"} | Set the current genre |
File Player
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| fileplayer | GET | http://localhost:8000/api/fileplayer | JSON | The name of the current folder and file |
| fileplayer | PUT | http://localhost:8000/api/fileplayer Request body: {"folder":"/home/pi/music", "file":"test.wav"} | Set the new player state | |
| orders | GET | http://localhost:8000/api/orders | JSON | List of playback order items |
| order | GET | http://localhost:8000/api/order | JSON | Get current playback order |
| order | PUT | http://localhost:8000/api/order Request body: {"playback.order": "cyclic"} | Set current playback order | |
| info | GET | http://localhost:8000/api/info | JSON | Information about current track |
| time | GET | http://localhost:8000/api/time | JSON | Current track time and total track time |
File Browser
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| filebrowser | GET | http://localhost:8000/api/filebrowser | JSON | Get the content of the default Music folder |
| filebrowser | GET | http://localhost:8000/api/filebrowser?images=true | JSON | The same as above but the output includes the additional property has_embedded_image. This request takes more time as there is the need to parse audio file. |
| filebrowser | GET | http://localhost:8000/api/filebrowser?folder="/home/pi/music" | JSON | Get the content of the folder defined by the URL parameter folder. Invalid HTTP URL characters should be encoded accordingly. |
Timer
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| timer | GET | http://localhost:8000/api/timer | JSON | Get the current timer state |
| timer | POST | http://localhost:8000/api/timer | Set the current timer state | |
| sleep | POST | http://localhost:8000/api/sleep | Sleep now | |
| wakeup | POST | http://localhost:8000/api/wakeup | Wake up |
Network
| Resource | HTTP Method | Request Example | Response | Description |
|---|---|---|---|---|
| network | GET | http://localhost:8000/api/network | JSON | Get current network information |
| wifi | GET | http://localhost:8000/api/wifi | JSON | Get the list of available Wi-Fi networks |
| wifi | POST | http://localhost:8000/api/wifi/connect | Connect to Wi-Fi network | |
| wifi | POST | http://localhost:8000/api/wifi/disconnect | Disconnect from Wi-Fi network |