Public API Beta

This API is in beta. It is ready to be built on and we keep to the compatibility rules below, but the endpoints are new, the list of them will grow, and we may still have to change something before calling it 1.0. If you rely on it, tell us at info@awesomeprog.com, so we know whom to warn.

The public API gives other sites and apps read-only access to the AwesomeProg database: looking up artists and releases, a release's tracklist, and the upcoming releases. It answers JSON, needs no account and no key, and reads exactly what the site itself shows.

Getting started

Every endpoint lives under

https://srv.progfreak.com/api/public/v1

Searching for an artist, then reading its releases:

curl -A "YourSiteBot/1.0 (+https://your.site)" "https://srv.progfreak.com/api/public/v1/artists?query=anglagard"
curl -A "YourSiteBot/1.0 (+https://your.site)" "https://srv.progfreak.com/api/public/v1/artists/17/releases"

The next fifty prog releases, soonest first:

curl -A "YourSiteBot/1.0 (+https://your.site)" "https://srv.progfreak.com/api/public/v1/upcoming-releases?prog=prog&limit=50&offset=0"

The whole API is also described as an OpenAPI document, which most languages can generate a client from.

Using it

From your servers, send a User-Agent that names your site, such as YourSiteBot/1.0 (+https://your.site). Tell us what it is and we will know the requests are yours.
From your web pages (embedding it), the browser only lets your pages read the answers once we have added your site's address to our list of API users. Write to info@awesomeprog.com with the address, e.g. https://www.your.site.
Please keep it reasonable: cache what you read, page through long lists rather than asking for all of them at once, and link each artist and release to its page here – every one comes with its url.
Ids are stable. A release that turns out to be a duplicate is merged into the other one, and asking for it by its old id answers with the release it was merged into.
Errors are plain HTTP: 404 for an id nothing has, 400 for a parameter out of range.

What we promise

Version 1 only grows. We may add endpoints, optional parameters, fields and values, so a client should ignore fields it does not know and read an unknown release type as other. We will not remove or rename anything, change a field's type or meaning, make a field that is always there optional, or make a parameter required. A change like that would come as a version 2, next to version 1 rather than in place of it. Every field is always sent, with null where there is no value.

Reference

Drawn from the OpenAPI document as the API serves it right now.

Loading the reference…