Simply Aloud API v1

All webservices are implemented using the standard JSON over HTTP, so all requests and response will declare the header “Content-Type” as "application/json".

Security

A secure communication in ensured by the TLS 1.2 protocol (HTTPS) and a custom HTTP Digest authorization header encrypted by the algorithm HMAC SHA512. Every request must include the header "Authorization" with a server to server key. Authorization is a Base64 encoded representation of the string "timestamp:apiClientId:signature" where:

PHP snippet to generate the Authorization header

private function generateAuthorization()
{
    $timestamp = time();
    $hashData = $timestamp . ":" . $this->clientId;
    $signature = hash_hmac("sha512", $hashData, $this->clientSecret);

    $string_to_encode = $timestamp . ":" . $this->clientId . ":" . $signature;
    $authorization = base64_encode($string_to_encode);

    return $authorization;
}

If you need support write to info@simplyaloud.com

Result Codes

200: Success
400: Bad Request
401: Unauthorized
404: Not Found

Success result example

{
   "status": 200,
   "message": "Success",
   "data": { ... }
}

Unsuccessful result examples

{
  "status”: 401
  "message": "Unauthorized"
  "data": null
}
{
  "status": 400,
  "message": "Bad Request. Required String parameter 'id' is not present",
  "data": null
}



Common result objects

Content

Field Type Description
id String (Mandatory) Shared ID
url String (Mandatory) Url of the resource
code String Code used to label and order the content
title String Title
publishDate ZonedDateTime Zoned Date Time with pattern "yyyy-MM-dd'T'HH:mm:ssZ"
Example: "2018-06-09T11:00:00+0200"
category String Content category
imageUrl String Public image url
audioUrl String Public audio file url
audioFileType String Audio content-type
Example: "audio/mpeg"
audioDuration Integer Audio duration in seconds
active Boolean Wheter the audio content is active or not. It can be active only if the audioUrl field is populated



Webservices

1. Content - Save

Description: Create or update a content into Simply Aloud

URL: https://www.simplyaloud.com/api/journal/v1/content/save

Type: POST


REQUEST PARAMETERS

Field Type Description
id String (Mandatory) Shared ID
url String (Mandatory) Url of the resource
code String Code used to label and order the content
title String Title
publishDate ZonedDateTime Zoned Date Time with pattern "yyyy-MM-dd'T'HH:mm:ssZ"
Example: "2018-06-09T11:00:00+0200"
category String Content category
imageUrl String Public image url

RESPONSE (data)

Content (See Content result object).


Example (Success)

REQUEST: http://www.bricking.news/api/journal/v1/content/save

{
    "id": "1234ABCD",
    "url": "https://en.wikipedia.org/wiki/Online_newspaper",
    "code": "001",
    "title": "Online newspaper",
    "publishDate": "2018-06-09T11:00:00+0200",
    "category": "Technology"
}

RESPONSE:

{
    "status": 200,
    "message": "Success",
    "data": {
        "id": "1234ABCD",
        "url": "https://en.wikipedia.org/wiki/Online_newspaper",
        "code": "001",
        "title": "Online newspaper",
        "publishDate": "2018-06-09T11:00:00+0200",
        "category": "Technology",
        "imageUrl": null,
        "audioUrl": null,
        "audioFileType": null,
        "audioDuration": 0,
        "active": false
    }
}

Example (Bad Request)

REQUEST: http://www.bricking.news/api/journal/v1/save

{
    "url": "https://en.wikipedia.org/wiki/Online_newspaper"
}

RESPONSE:

{
    "status": 400,
    "message": "Bad Request. 1) Field 'id' rejected value [null] because may not be empty.",
    "data": null
}



2. Content - Get

Description: Returns the details of a previously stored content

URL: https://www.simplyaloud.com/api/journal/v1/content/get/{id}

Type: GET


REQUEST PARAMETERS

Field Type Description
id String (Mandatory) Shared ID

RESPONSE (data)

Content (See Content result object).


Example (Success)

REQUEST: https://www.simplyaloud.com/api/journal/v1/content/get/1234ABCD

RESPONSE:

{
    "status": 200,
    "message": "Success",
    "data": {
        "id": "1234ABCD",
        "url": "https://en.wikipedia.org/wiki/Online_newspaper",
        "code": "001",
        "title": "Online newspaper",
        "publishDate": "2018-06-09T11:00:00+0200",
        "category": "Technology",
        "imageUrl": https://storage.simplyaloud.com/public/assets/images/headphones_grey.png",
        "audioUrl": "https://storage.simplyaloud.com/public/content/10/EKBC6xWKnMb8KGxwuk7XFlqXxgjNxCKQ_679.mp3",
        "audioFileType": "audio/mpeg",
        "audioDuration": 118,
        "active": true
    }
}

Example (Bad Request)

REQUEST: https://www.simplyaloud.com/api/journal/v1/content/get/NOT_EXISTING_ID

RESPONSE:

{
    "status": 404,
    "message": "Not Found",
    "data": null
}