Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

EthosCE has a powerful RESTful webservice that can be used to send or retrieve information from an EthosCE website through HTTP requests.

The web service extension supports full CRUD (Create, Read, Update, Delete) for resources:

  • Create: HTTP POST /<entity type name>
  • Read: HTTP GET /<entity type name>/<entity id>.<format
  • Update: HTTP PUT /<entity type name>/<entity id>.<format>
  • Delete: HTTP DELETE /<entity type name>/<entity id>

  • JSON and XML are fully supported "Formats" for sending and receiving data.

Examples

Any language that can make HTTP requests can be used. Here are some examples in PHP/CURL:

Retrieving a user profile
<?php
// Retrieve a profile in XML:
$curl = curl_init('http://your-domain.com/profile2.xml?user=2');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); // Your web service user credentials go here.
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
print $response;

NOTE: When creating or updating an entity:

  • an additional token is required for security, and must be passed in a"X-CSRF-Token" HTTP header
  • you must specify the format being posted in an HTTP header, either "application/json" or "text/xml"
Creating a course
<?php
$curl = curl_init('http://your-domain.com/restws/session/token');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); // Your web service user credentials go here.
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
$token = curl_exec($curl);
// The token looks like "q71OBx05wtECfjA0KmXf6wiktewrywNhkMZv-OcfyOA%"

// Build a course to send, in JSON. The fields and allowed values are available on the full documentation site.
$course = array(
  'title' => 'my new course',
  'type' => 'course',
  'field_course_summary' => array(
    'value' => 'this is the summary<b>This is bold</b>',
    'format' => 'full_html'
  ),
  'author' => 1,
  'status' => 1,
);
$json = json_encode($course);
$curl = curl_init('http://your-domain.com/node.json');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials go here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-CSRF-Token: $token", "Content-Type: application/json"));
$response = json_decode(curl_exec($curl));
// The response looks like (JSON decoded)
/*
stdClass Object
(
    [uri] => http://your-domain.com/node/33
    [id] => 33
    [resource] => node
    [uuid] => 5121134e-dbfa-4011-939e-180290a02618
)
*/

Updating a course's title. Note the usage of "PUT" instead of "POST"

Updating a course's title
<?php

$curl = curl_init('http://your-domain.com/restws/session/token');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
$token = curl_exec($curl);
print "Received token: " . $token . "\n";

// Token looks like "q71OBx05wtECfjA0KmXf6wiktewrywNhkMZv-OcfyOA%"
// Build a course
// The fields and allowed values are available on the full documentation site.
$course = array(
  'title' => 'my updated course',
);
$json = json_encode($course);
$curl = curl_init('http://your-domain.com/node/30');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-CSRF-Token: $token", "Content-Type: application/json"));
$response = curl_exec($curl);
print $response;


You can also list entities using the webservice, and apply sorts and filters.

Listing awarded credit
<?php

// Show recent credit awarded
$curl = curl_init('http://your-domain/course_credit_awarded.xml?uid=2&sort=date&direction=DESC');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
print curl_exec($curl);

Errors

Errors are reported from the RESTful web service with HTTP codes:

  • 404: Not Found
    • The resource was not found
  • 403: Forbidden
    • The web service user does not have permission to use the resource
  • 406: Not Acceptable
    • The data sent to the web service is not in an acceptable format or is missing required fields. Check the documentation for the correct fields and format.
  • 200: OK
    • The web service call is successful. Data may or may not be returned depending on the operation.
  • 201: Created
    • The web service call created data

  • No labels