Skip to main content

Developing in Cascade how to

Getting started with REST

These examples all perform the same task: read the page news/2003/best-of-show in site example.com, change its title, and issue an edit. See Operations for the full endpoint reference.

Several examples below pass credentials as u and p query parameters. That form puts a password in URLs and server logs — prefer an API key in an Authorization header, as the later examples show.

JavaScript with jQuery

JavaScript 
$.get("http://localhost:8080/api/v1/read/page/example.com/news/2003/best-of-show?u=hill&p=hill", function(data) {
  if (data.success) {
    data.asset.page.metadata.title = 'New title';
    $.post("http://localhost:8080/api/v1/edit?u=hill&p=hill", JSON.stringify({
      'asset': data.asset
    }), function(data) {
      if (data.success)
        console.log('Success');
      else
        console.log('Error occurred when issuing an edit: ' + data.message);
    }, 'json');
  } else {
    console.log('Error occurred when issuing a read: ' + data.message);
  }
}, 'json');

JavaScript with fetch

The same example without jQuery or any other library. It runs from the browser's developer tools console.

JavaScript 
fetch("http://localhost:8080/api/v1/read/page/example.com/news/2003/best-of-show", {
    "headers": {
      "Authorization": "Basic aGlsbDpoaWxs"
    }
  })
  .then(r => r.json())
  .then(data => {
    if (data.success) {
      data.asset.page.metadata.title = 'New title';
      fetch("http://localhost:8080/api/v1/edit", {
        method: 'POST',
        headers: {
          "Authorization": "Basic aGlsbDpoaWxs"
        },
        body: JSON.stringify({'asset': data.asset})
      })
        .then(r => r.json())
        .then(data => {
          if (data.success)
            console.log('Success');
          else
            console.log('Error occurred when issuing an edit: ' + data.message);
        });
    } else {
      console.log('Error occurred when issuing a read: ' + data.message);
    }
  });

JavaScript with async/await

JavaScript 
(async () => {
  const readResult = await fetch("http://localhost:8080/api/v1/read/page/example.com/news/2003/best-of-show", {
    headers: {
      "Authorization": "Bearer your-api-key"
    }
  });
  const readData = await readResult.json();
  if (readData.success) {
    readData.asset.page.metadata.title = 'New title';
    const editResult = await fetch("http://localhost:8080/api/v1/edit", {
      method: 'POST',
      headers: {
        "Authorization": "Bearer your-api-key"
      },
      body: JSON.stringify({asset: readData.asset})
    });
    const editData = await editResult.json();
    if (editData.success)
      console.log('Success');
    else
      console.log('Error occurred when issuing an edit: ' + editData.message);
  } else {
    console.log('Error occurred when issuing a read: ' + readData.message);
  }
})();

Reading a File's byte array contents

JavaScript 
(async (
  url = "http://localhost:8080/api/v1/read/file/example.com/image/sample.png",
  apiKey = "your-api-key"
) => {
  const readResult = await fetch(url, {
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  });
  const readData = await readResult.json();
  if (readData.success) {
    const encoder = new TextEncoder();
    const buffer = encoder.encode(readData.asset.file.text).buffer;
    const sliced = Array.prototype.slice.call(new Uint8Array(buffer), 0);
    console.dir(sliced);
  } else {
    console.log('Error occurred when issuing a read: ' + readData.message);
  }
})();

PHP

GET operations are straightforward. This reads a role with id 1:

PHP 
$reply = json_decode(file_get_contents('http://localhost:8080/api/v1/read/role/1?u=admin&p=admin'));
print_r($reply);

POST operations are simple with a small utility function to convert between PHP arrays and JSON:

PHP 
function apiOperation($url, $params)
{
    return json_decode(file_get_contents($url, false, stream_context_create(array('http' => array('method' => 'POST', 'content' => json_encode($params))))));
}

Which makes the read-then-edit example look like this:

PHP 
$reply = json_decode(file_get_contents('http://localhost:8080/api/v1/read/page/example.com/news/2003/best-of-show?u=hill&p=hill'));

if ($reply->success)
{
    $reply->asset->page->metadata->title = "A new title";
    $reply = apiOperation('http://localhost:8080/api/v1/edit?u=hill&p=hill', array('asset' => $reply->asset));
    if ($reply->success)
        echo "Success.";
    else
        echo "Error occurred when issuing an edit: " . $reply->message;
}
else
    echo "Error occurred when issuing a read: " . $reply->message;