Hey everyone!
As you (hopefully) already know - GGRadio 3 was released recently, the new site has tonnes of new features - nicer graphics and more
information and if you're reading this, you probably know that all requires an API.
So here's what's changed:
- The switch to JSON (finally)
- Addition of aggregation endpoints
- Addition of feeds/social services
- Addition of WebSocket
- Continuous integration
- Versioning
If you use any of the legacy apps for GGRadio, you may have noticed them showing {"song": "amazing song"} now - this is part of our final switch to a RESTful API that includes JSON responses - we're working to update all of these outdated (legacy) apps and hope to have them done within the next month or so.
I'll give a rundown on the points I've highlighted above, but if you want to integrate the API into your product, please view our
documentation
The Switch to JSON
Since GGRadio's V1 API that was released three years ago
we have stuck to it's "outdated" standards - aka plain text, it's finally time for a change. In V3 we added /json to the end of any endpoint to receive it's JSON output and quietly announced it in our
Discord - this was a beginning but I have to admit, even I didn't use it.
Error messages sent their
Express.js errors (yuck, right?)
and the API frequently crashed - more on this later.
Now the API is fully JSON and it's not optional - this was quite a bold move but the decision was made to do it without a slow rollout - otherwise it would've never been done.
Again, please read the docs for more information on this.
In previous versions of the GGRadio/tmw.media API - nothing has been in one place, in order for the website (ggradio.net) to get it's currently playing data it had to make two requests every 10 seconds - i mean, it works, right?
The aggregation endpoints means there's much less work for your client - we just do all of the work quietly on tmw.media's server (woah!) check it out:
https://api.tmw.media/ggradio/aggregates
This single endpoint not only gives us the live playing data, but also the previous 4 songs, details of our gateway, artwork and more! Super cool :tup:
On previous versions of the GGRadio site, the most information we gave was a little box that was manually written in HTML to show the announcements - API v4 brings out "feeds" system across which allows public access to all of our latest news, announcements, YouTube uploads & Tweets!
Check out
http://api.tmw.media/ggradio/social?platform=aggregates
This lets GGRadio 3 bring you into the loop of what we're actually doing apart from just playing some dank tunes.
As mentioned above, all previous versions of GGRadio have had a setInterval loop constantly pinging our API to check if the song had changed - this really isn't efficient for you - or us.
API v4 & GGRadio 3 introduce a new fangled websocket approach to this - just like your phone being sent messages, our API server sends your computer the latest song & recently played along with artwork and links as they change, no constant checking. Better for everyone involved.
Continuous Integration (CI)
This is more of an internal thing, but we've recently deployed CI into our infra - you may have noticed outages of our API in the past lasting upwards of 10 minutes during an API update, this will no longer happen, updates are tested on our staging server (oh yeah, if you want to try the bleeding edge API:
https://staging.tmw.media/api - don't rely on it for production PLEASE, it doesn't have the retention systems our production APIs have!) after staging they will be moved into production - there's no outage has the new version comes up - runs a couple tests and then takes over from the old one, not even a blip - even web-sockets are gracefully handed off. No console filled with errors!
All previous versions of our API have been statically versioned, meaning if we have breaking changes they effect everyone - instantly. V4's deployment has stopped this for good - when V5 swings around, you'll be able to beta test it at api.tmw.media/v5/endpoint along with the beta documentation that follows it.
We aim to follow this structure for future releases: (for this example I'm using V5, this will apply to any future version)
- V5 finishes internal testing
- Pushed to staging.tmw.media/api/v5
- Documentation released on our public pages
- V5 bugs are found & resolved - staging and documentation updates.
- Other modules are brought up to the v5 standard (Authentication, feeds, requests etc...)
- Documentation for other modules are released
- One month later
- 2 weeks later - A small batch of website users are moved onto V5 for extra testing
- 1 week later - a proportion of requests to api.tmw.media are moved to the V5 standard (if running on latest release channel - /v4 direct users are NOT effected)
- 1 week later - V5 becomes production, v4 gains LTS tag
- 1 year later - V4 becomes tagged "legacy"
- 1 month later - V4 is modified to display warnings to users
- V4 is removed from the supported list on api.tmw.media/versions
- 1 month later - V4 is placed in a suspended state, all requests will result in Err: VERSION_DEPRECATED
- Unknown amount of time later - All V4 modules shutdown and pulled from CI
If you're just a listener you shouldn't even notice the API - it should just be pixie magic!