Quick Start Guide

Introduction

In this guide you will be shown how to use the Radioplayer Partner API (WRAPI) to make two simple example calls to the Radioplayer metadata service.

These calls will return:

  • A list of available radio stations
  • Full details about a station you select from the list.

To do this you will build a simple example application using sample code from Radioplayer's code libraries.

The steps involved are:

  1. Obtaining the necessary credentials
  2. Downloading an example middleware client from our code libraries
  3. Editing your credentials into the client
  4. Connecting to the API and receiving the responses
  5. Displaying the responses.

Please note: these instructions show the steps for building the example application in Java, but the principles involved are applicable to any of the code samples in the library.

Prerequisites

To use this Quick Start Guide you will need:

  • An API key for the Radioplayer Partner API (WRAPI)
  • A private key, or PEM file, for your Radioplayer account
  • End user application nodes
  • Access to the Radioplayer sample code libraries, available here.
  • A Java environment with the following packages installed.

All of these prerequisites require you to have a current Radioplayer developer account. To open a trial account, please contact us.

Obtaining your credentials

To get access to the Radioplayer metadata service you require two keys:

  • An API key
  • A PEM certificate.

Both of these are sent to you when your business opens a developer account with Radioplayer.

These will be inserted programmatically into the signed HTTPS requests you send to Radioplayer, so keep them safe.

Creating the middleware client

The middleware client handles the authentication of your credentials and returns data from the Radioplayer metadata service.

You can build a client using sample code from our libraries page

In this guide, we will edit the Java client to supply authentication credentials to the Radioplayer metadata service and build a simple request to the Radioplayer metadata service:

Signing your HTTPS requests

With the client selected from the code samples you can now supply your authentication credentials to it by editing the code. These will be sent with each HTTPS request the client sends.

For a stepped walkthrough of an example of authenticating a signed HTTPS request, please see the Authentication Guide. Here we will simply discuss the request and how it is constructed.

Here is the authentication code:



    final String keyId = "your-key-id";

    // Load in the PEM file
    File pemFile = new File( getClass().getResource(keyId + ".pem").getFile());
    Key k = PEMHelper.readKey(pemFile, new char[]{ '\0'});
    // This PEM file has no passphrase

    // Generate the Signer, for signing our requests
    Signer signer = new Signer(k, new UserFingerprintKeyId(keyId));

    // We want to make sure that our requests are encoded with
    the correct algorithm - rotate the key so that it uses RSA_SHA256
    Challenge challenge = new Challenge("",
        Constants.DEFAULT_HEADERS, Arrays.asList(
            new Algorithm[] {Algorithm.RSA_SHA256} ));
    signer.rotateKeys(challenge);

    // Dates should be formatted in GMT using DATE_FORMAT_RFC1123
    DateFormat df = new SimpleDateFormat(RequestContent.DATE_FORMAT_RFC1123);
    df.setTimeZone(TimeZone.getTimeZone("GMT"));

    // Create the content to sign and sign it
    RequestContent.Builder requestContentBuilder = new RequestContent.Builder();
    requestContentBuilder.addHeader("date", df.format(new Date()));
    RequestContent requestContent = requestContentBuilder.build();
    Authorization auth = signer.sign(requestContent);

    // Create the full signature with the keyId, and algorithm
    String sig = new StringBuilder().append("Signature keyId=")
                .append("\"").append(keyId).append("\"")
                .append(",algorithm=\"rsa-sha256\",signature=\"")
                .append(auth.getSignature())
                .append("\"").toString();

Having created the signature, it is now time to make the request.

In this example the request is to return the details for a single station, based on its rpuid - the unique identifier for each station.

The endpoint for this request is https://api.radioplayer.org/v2/stations/8261004, with 8261004 standing for a particular station - "Fun Kids".



    // Now make the request - get station details
    HttpGet request = new HttpGet("https://api.radioplayer.org/v2/stations/8261004");

    // Add date and authorization headers
    request.addHeader("date", df.format(requestContent.getDateGMT()));
    request.addHeader("Authorization", sig);

    // Submit the request
    HttpClient client = HttpClientBuilder.create().build();
    HttpResponse r = client.execute(request);

    // Admire output
    r.getEntity().getContent().transferTo(System.out);

Because there are no applied parameters, this request will return every single piece of information attached to this ID.

Applying parameters to your requests

You can filter what information comes back from the Radioplayer Partner API (WRAPI) by applying parameters to the request.

For instance, if instead of using:



HttpGet request = new HttpGet("https://api.radioplayer.org/v2/stations/8261004");

which would return everything in the metadata service on this station, you could filter your results using parameters.

In this example, the include parameter is being used to just return livestream source URLs from the request:



HttpGet request = new HttpGet("https://api.radioplayer.org/v2/stations/8261004?include=streamsource");

This would return the following subset of the data on that station:


{
    "data": [
        {
            "liveStreams": [
                {
                    "streamSource": {
                        "url":
"https://listen-funkids.sharp-stream.com/funkids.aac?device=rpmobilelow",
                        "mimeValue": "audio/aac"
                    },
                    "bitRate": {
                        "target": 48000
                    }
                },
                {
                    "streamSource": {
                        "url":
"https://listen-funkids.sharp-stream.com/funkids.mp3?device=rpmobilehigh",
                        "mimeValue": "audio/mpeg"
                    },
                    "bitRate": {
                        "target": 128000
                    }
                },
                {
                    "streamSource": {
                        "url":
"https://listen-funkids.sharp-stream.com/funkids.mp3?device=rpweb",
                        "mimeValue": "audio/mpeg"
                    },
                    "bitRate": {
                        "target": 128000
                    },
                    "streamRestriction": {
                        "value": "web",
                        "relationship": "allow"
                    }
                }
            ],
            "rpuid": "8261004"
        }
    ],
}

You can test these results yourself, in code or by using the console tool.

Learn more...

This has just been a tiny example of how the Radioplayer Partner API (WRAPI) can help you develop content-rich radio interfaces for your media apps.

To find out more, see our:

  • API documentation to explore what the Radioplayer Partner API (WRAPI) can do for you
  • Use cases to discover the unique features the Radioplayer Partner API (WRAPI) can offer you
  • How-to guides to optimise how you use the Radioplayer Partner API (WRAPI) in your bespoke applications.

Any questions, comments? Please contact us.