...
- 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:
Contents
Table of Contents | ||
---|---|---|
|
Authentication
All web service requests require login, before accepting a query. A separate login call is not required for authentication. Login credentials are sent via HTTP Basic Authentication headers, in the requests. An example of the structure in PHP is shown below. Note, that all calls require this login to function properly.
Code Block | ||||
---|---|---|---|---|
| ||||
<?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, "restws_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"
Code Block | ||||
---|---|---|---|---|
| ||||
<?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); |
Info | ||
---|---|---|
| ||
A web service user account must meet proper naming convention to be valid for authentication. By default, the username must always start with "restws". |
Querying EthosCE
Clients may use GET calls, to pull information from the system, including applying advanced filters and sorting. Reference the Web Service Data Structures page for more information on each content type, their available fields, and accepted values. Most fields, including custom, are available to filter against. Multiple filters may be added to the query string via ampersands. The examples below detail common URL filter configurations.
Supported Operators
Operator | Syntax | Example | Result |
---|---|---|---|
> | [gt]= | user.json?uid[gt]='100' | All users with uids greater than (but not equal to) 100 |
>= | [ge]= | node.json?created[ge]='1478044800' | All nodes created before or equal to 11/02/2016 - 00:00 UTC |
< | [lt]= | user.json?uid[lt]='500' | All users with uids less than (but not equal to) 500 |
<= | [le]= | user.json?login[le]='1478278815' | All users who have logged in before or equal to 11/04/2016 - 17:00 UTC |
<> | [ne]= | credit_awarded.json?type[ne]='attendance' | All awarded credit that is not Attendance |
= | [eq]= | credit_awarded.json?type[eq]='ama' credit_awarded.json?type='ama' | All awarded AMA credit |
Contains | [ct]= | user.json?mail[ct]='ethosce.com' | All users with an e-mail address which contains 'ethosce.com' |
Starts with | [sw]= | user.json?name[sw]='jsmith' | All users who have a username that starts with 'jsmith' |
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
<?php $curl = curl_init('http://your-domain.com/node.json/course_credit_awarded.xml?uid=2&sort=date&direction=DESC'); curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, "restws_admin:webservicepw"); //Your credentials gogoes here curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST'); curl_setopt($curl, CURLOPT_POSTFIELDS, $json);// Your session token and content type curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-CSRF-Token: $token", "Content-Type: application/json")); $response = json_decode(print 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 ) */ |
...
Code Block | ||||
---|---|---|---|---|
| ||||
<?php $curl = curl_init('http://your-domain.com/restws/session/token/course_credit_awarded.xml?date[ge]=1471651200&date[le]=1471737600'); curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, "restws_admin:webservicepw"); //Your credentials goes here curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); // Your session token and content type curl_setopt($curl, CURLOPT_CUSTOMREQUESTHTTPHEADER, '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);array("Content-Type: application/json")); print curl_exec($curl); |
Code Block | ||||
---|---|---|---|---|
| ||||
<?php $curl = curl_init('http://your-domain.com/node/30/course_credit_awarded.xml?type[ne]=ama'); curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, "restws_admin:webservicepw"); //Your credentials goes here curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($curl, CURLOPT_POSTFIELDS, $json); // Your session token and content type curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-CSRF-Token: $token", "Content-Type: application/json")); $response =print curl_exec($curl); print $response; |
You can also list entities using the webservice, and apply sorts and filters.
Code Block | ||||
---|---|---|---|---|
| ||||
<?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); |
...
Date Formatting
There are 2 date formats used when interacting with the web service, epoch and ISO 8601. The call being made informs which format to use. All GET calls, to pull information from EthosCE, require the URL friendly epoch time. A call for creation or update must use the database compatible ISO 8601 format (Y-m-d\TH:i:sZ). Additionally, both date formats must be converted to UTC before being sent, to ensure data integrity between systems.
Info | ||
---|---|---|
| ||
Entered local time: December 31, 2014, 12:00PM EST Converted to UTC/GMT: December 31, 2014, 5:00PM UTC ISO 8601 format: 2014-12-31T17:00:00Z Epoch format: 1420045200 |
Error Returns
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.
- If this error is seen often, verify the session authentication step have been completed.
- 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
Example Scenarios
The following examples of standard calls to EthosCE are written in PHP, in JSON, using the Curl library.
Child pages (Children Display) | ||||
---|---|---|---|---|
|
Additional Links
Child pages (Children Display) | ||
---|---|---|
|