Skip to content

4.1 5.0 Migration Notes

Cameron Fleming edited this page Jul 27, 2019 · 1 revision

Changes from 4.0 to 4.1 / WebSocket 4.0 -> 5.0 API V4.1 (Miru X) is now in staging, awaiting release in early August.

This update makes a small amount of changes to the HTTP API, but entirely overhauls the WebSocket.

As always, this is not a guide on how to use v4.1 and just highlights the differences between it and 4.0, for instructions on integrating 4.1, please see the v4.1 docs.

Rollout changes

In the diff, you may see two new scripts under the tools/ directory. These scripts allow us to deploy updates to staging/production systems with much less disruption. While is used as part of the automated deployment system, is a feature that was meant for 4.0, but was only just implemented.

Now, a few seconds before the API upgrades begin, a message is sent to all connected websockets with the following data:

{"cmd:" "disconnect", "reason": "api_restarting", "try_again": 10000}

When your app receives this message, it should wait the amount of time specified in the 'try_again' variable before reestablishing a connection.

You may also display a warning to the user telling them song updates will be momentarily behind schedule while automatic system updates are applied.

The WS will be closed by the server, so ensure you're handling the WS Close event on your application.

Deployment schedule

As outlined in the original 4.0 release post, 4.1 will undergo a staged rollout. Though, as it is not a major release, it will be brought into production faster than future versions.

NOTICE: WebSocket 5.0 will be fast-tracked into production

Due to a development oversight, the 5.0 release of our WebSocket platform will be fast-tracked into production, becoming active on production on the day of v4.1 release. If you are making use of our WebSocket, please ensure you have updated your client software before v4.1 production 'switch-on'

Release Cycle Dates

More information about these milestones is listed below.

EXT = Exact dates

NET = Estimated dates

EXT 15/07/2019 - REST v4.1 FEATURE FREEZE - Complete

  1. EXT 18/07/2019 - REST v4.1 available to STAGING. - Complete
  2. EXT 25/07/2019 - WS v5.0 available to STAGING. - Complete
  3. EXT 01/08/2019 - REST v4.1 available to PRODUCTION - Awaiting date
  4. EXT 10/08/2019 - WS v5.0 MADE PRODUCTION - Awaiting date
  5. EXT 10/08/2019 - REST v4.1 MADE PRODUCTION - Awaiting date
  6. NET 20/08/2019 - REST v4.0 MADE DEPRECATED - Awaiting date
  7. NET 2020 - REST v4.0 DEACTIVATED - Awaiting date

1 - REST 4.1 available to staging

As of the 18th of July 2019, API v4.1 is available to all users of - for example

2 - WS v5.0 available to staging

As of the 25th of July 2019, the WebSocket 5.0 is available to users of

This is an entirely new version of the WebSocket, so please see the WS5 documentation.

3 - REST v4.1 available to production

On the 1st of August 2019, API v4.1 will be merged into the master branch, and thus, made available to all users.

Please note, this is an 'available' release - meaning the default API will remain 4.0 for 10 days.

For example: will use v4.0, while will use v4.1.

4 - WebSocket 5.0 release

On the 10th of August 2019, the WS5 will be merged into production and made default. All clients must be upgraded as 4.0 will be removed effective immediately.

This is due to an engineering oversight during the build of v4.0, but has been resolved. So all future updates of the websocket will be versioned.

5 - REST 4.1 made production

On the 10th of August 2019, at the same time as WebSocket 5.0 release, the REST API v4.1 will be defaulted. Meaning all non-versioned API endpoints (i.e will point to the v4.1 endpoint.

We are fast tracking this release as there aren't any 'breaking' changes to the API, just removal of data that is un-used.

6 - V4.0 Deprecation

10 days after switch-over, v4.0 will be marked deprecated on the /versions endpoint. We will continue to monitor version usage.

Some data will have a 'PLEASE UPGRADE APP' notice in them as soon as deprecation begins.

7 - V4.0 Removal

At some point in 2020, once our stats say nobody is using API v4.0, we will deactivate it from the API. We will alert everyone 10 days before doing so.

Deployment Notes

This version implements a new router, this may have an effect on some headers sent from the API, including x-powered-by.

HTTP API Changes

Most of the API changes in this release are backend related. Such as the new routing system, however, some items have been removed/changed.


We have removed some useless information from some endpoints

For example, "artwork_details" in aggregates/recently played has been removed, as it contained useless information that just made payloads larger.

This update is part of our journey to allow GGRadio to work on slower/less reliable connections in preparation for mobile apps.


From the beginning of v4.0, there has been two names for the feeds system. Both 'social' and 'feeds' - we have now entirely scrapped the name 'social' and all endpoints use 'feeds'

Each service that the API handles has feeds, such as twitter, news and announcements.

A 4.0-HOTFIX was released in June of 2019 removing news/announcements from GGRadio. These have both been reinstated.


Since 4.0, the API has been collecting stats during it's normal operations.

Such as user-agents, the number of connections, 404s (to assist in development) and usage stats per endpoint.

In 4.1, we have not only moved the endpoints, but added even more useful information.

/stats now 301's to /telemetry/stats

/telemetry/versions - Shows the amount of connections to each active version

/telemetry/ws - Shows active WS sessions, what they're listening for.


That concludes the changes to REST 4.1 - expect changes to our requests/voting/shout-out system in 4.2, preparing for release sometime in 2019.

WebSocket Changes

As noted above, these changes will be active on the production API on the 10th of August, 2019, with no option to use the older version.


The websocket now works on a sub-pub model. When you connect, you get a 5 second window to tell the API what you want to do. For example, if you want to subscribe to GGRadio song changes, you must send

{"cmd": "add_channel", "channel_type": "radio", "channel_name": "ggradio"}

You may add multiple channels, but cannot remove them. Simply relaunch the socket and re-add new channels.


Again, to attempt to reduce the data-footprint of GGRadio, in preparation for mobile users, we will no longer automatically send keepalive messages.

The client is expected to send a keep-alive every 30 seconds, and if one is not sent using the following command, the connection will be dropped.

{"cmd": "keep_alive"}

Your client will receive an "ack" command shortly after. If you do not get an ack, we recommend restarting your WebSocket connection.

We are open to any suggestions on how to improve our websocket in the future, so please drop us a message in the GGRadio Discord Server.

Final notices

We have recently instated a new server that will allow users of to listen to GGRadio again. We ask that anybody still using this outdated endpoint changes as soon as possible.

We hope you find these updates a welcome change and as always we're open to suggestions for future versions.

Please use the actual documentation while writing your software. This is just a changelog.

API V4.1 is currently in the devel/release cycle. Please see API docs for upcoming changes in August.

Clone this wiki locally
You can’t perform that action at this time.