...
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. Popular web service
HTTP Basic Authentication in
...
curl
Code Block | ||
---|---|---|
| ||
<?php curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, "restws_admin:webservicepw"); // Your web service user credentials go here. -X 'https://client.hosted.test.cloud.ethosce.com/user.json' --header 'Authorization: Basic cmVzdHdzX3JheTpXZWJzZXJ2aWNlMTIzIQ==' |
Info |
---|
Warning!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.
...
Return all credit awarded to user 2, sorted by awarded date
Code Block | ||
---|---|---|
| ||
<?php $curl = curl_init('httphttps://your-domainclient.hosted.test.cloud.ethosce.com/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 goes here curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); // Your session token and content type curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json")); print curl_exec($curl); |
Return all credit awarded after or on 08/20/2016 but before 08/21/2016
Code Block | ||
---|---|---|
| ||
<?php $curl = curl_init('httphttps://your-domainclient.hosted.test.cloud.ethosce.com/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_HTTPHEADER, array("Content-Type: application/json")); print curl_exec($curl); |
Return all credit awarded that is not AMA
Code Block | ||
---|---|---|
| ||
<?php $curl = curl_init('httphttps://your-domainclient.hosted.test.cloud.ethosce.com/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); // Your session token and content type curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json")); print curl_exec($curl); |
Date Formatting
There are 2 date formats used when interacting with the web service, epoch and ISO 8601. The format used is dependent on what piece of data you wish to reference, usually either a property or a field. Additionally, both date formats must be converted to UTC before being sent, to ensure data integrity between systems.
Info |
---|
Entered local time: July 28 2018 08:00AM EDT |
Info |
---|
A note on sending Date fields in queriesWhen using date fields as a parameter, the format must match the field you are referencing. As general guide, in courses, all added form fields, like custom fields, are formatted as ISO, and most date properties, like created and updated, are timestamps. Additionally, date fields with end dates require an added parameter to reference the correct date field. Unix timestamp fields require an epoch timestamp format in the parameter, and are usually single date properties. ISO date fields are more complex. They may have an End date, such as the expiration date in the Course Date field. These require an additional parameter to specify which of the two fields you would like to compare against, the start date (value) or the end date (value2). Formatting an ISO date field with an end date i.e. Course Date (field_course_date), Event/Session date (field_course_event_date), or a custom form field Formatting an ISO date field without an end date i.e. Course Date (field_course_date), Event/Session date (field_course_event_date), or a custom form field Formatting a unix timestamp field for 2017-12-25 i.e. created and updated |
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
...