Skip to main content
Edmentum Support

API Technical Reference

PLATO REST Web Service Interface

The PLATO REST API allows you to manage PLATO Learning Environment (PLE) and Vcourses data around locations, classes, administrators instructors and learners.

Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.
NOTE:The documentation outlined below encompasses the full extent of resources available to organizations who wish to develop an API or SSO connection to PLE for their systems. 

Base URL

All URLs referenced in the documentation have the following base:

Test Environment: https://api.nextple.platoweb.com

NOTE: The test environment is regularly purged and mirrored to the production environment. This may happen without warning.

Production Environment: https://api.ple.platoweb.com

 

Credentials and Security

All requests to PLATO's REST API require you to authenticate. Use HTTP basic auth to convey your identity to the API when making requests.

Your Basic Auth User Name is a combination of your PLE Account Login and PLATO Name separated by a pipe. So if your PLE or Vcourses Account Login is "ps" and your PLATO Name is "user1" the basic auth username would be "ps|user1".

Your password will be the same password.

All requests will be made of the HTTPS protocol. HTTP is not supported.

 

About REST (REpresentational State Transfer)

We designed the PLE API in a RESTful way, so that it is simple and straightforward.

For more information on REST, we would recommend Wikipedia or for more information about RESTful web services, the O'Reilly RESTful Web Services book is excellent.

 

HTTP Status Reference

Standard HTTP statuses are used for all fault conditions on responses that are not "200 OK" statuses. Below is a reference of some common scenarios for 400,404 and 409 statuses that may help you troubleshoot problems if you receive those errors.

  • 400 Bad Request
    • This status is typically returned when an element fails data validation.

    • An example of this would be an invalid email address.

  • 404 Not Found
    • This status will be returned when a resource you are trying to access does not exist.

    • An example of this would be when you would try to create a learner in a location that does not exist.

  • 409 Conflict
    • This status can be compared to a Primary Key violation. 409 is returned when a resources unique data is attempted to be created more than once. An example of unique resource data would be

      • PLATOName for a user of any type Learner/Instructor/Admin

      • Class Name for a class


         

Data Formats

The API provides the ability to transmit data in either a JSON or XML format. Unless you are using client side scripting such as jQuery or JavaScript we recommend using the XML interface. The details of these formats is included in the detailed reference below.

It is very important that as you issue API requests you include the appropriate Content-Type header with the HTTP request. Use the following values for the different data types:

JSON: Content-type: application/json

XML: Content-type: text/xml

 

Detailed Reference

Click here for more detailed information on the actions available in the PLATO API. If prompted for credentials you can use the following:
Username: psd01|api
Password: qatest

 

Sample walk through using Fiddler

Unless you are very familiar with developing against REST services using your development toolset and languages we highly recommend using raw HTTP requests using a tool and/or your browser to formulate your requests first to ensure everything works.

Once you have completed the testing this way, you can then emulate those requests in your development toolset.

This tutorial provides a walk through of using some of the basic PLE API functions with Fiddler:

PLATO Learning API Fiddler Tutorial

Click the link below for more information on how to use Fiddler:

http://www.fiddler2.com/Fiddler/help/

 

Code Samples

C# (Using XML data type)

Required Namespaces

using System;
using System.IO;
using System.Net;
using System.Text;
using System.Web;

 

Code

//all of the below variables should be changed to your specific values
string locationName = HttpUtility.UrlPathEncode("School 1");
string pleAccountLogin = "login";
string pleAdminPLATOName = "platoname";
string pleAdminPassword = "password";

Uri address = new Uri(string.Format("https://api.nextple.platoweb.com/Location/{0}/Learner", locationName));

// Create the web request 
HttpWebRequest request = WebRequest.Create(address) as HttpWebRequest;

// Set type to POST and set the appropriate content type
request.Method = "POST";
request.ContentType = "text/xml";

// create the body of the message. You may want to dynamically build your XML. This is done as a string for readability
//all values in the XML should be chaged to your specific values
string xmlBody = @"<Learner xmlns=""plato.api.domain"">
                    <ActivationDate>" + DateTime.Now.ToString("O") + @"</ActivationDate>
                    <EmailAddress>testuser@test.com</EmailAddress>
                    <FirstName>TestFirstName</FirstName>
                    <Grade>K</Grade>
                    <LastName>TestLastName</LastName>
                    <PLATOName>testPLATOName23</PLATOName>
                    <Password>p@ssword1</Password>
                    <SISId>1234567</SISId>
                    <StateId>MN</StateId>
                    <Status>Active</Status>
                    </Learner>";


// Create a byte array of the data we want to send 
byte[] byteData = UTF8Encoding.UTF8.GetBytes(xmlBody);

// Set the content length in the request headers 
request.ContentLength = byteData.Length;
request.Credentials = new NetworkCredential(string.Format("{0}|{1}", pleAccountLogin, pleAdminPLATOName), pleAdminPassword);

// Write data 
using (Stream postStream = request.GetRequestStream())
{
    postStream.Write(byteData, 0, byteData.Length);
}

// Get response 
try
{
    using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
    {
        // Get the response stream 
        StreamReader reader = new StreamReader(response.GetResponseStream());
        string output = reader.ReadToEnd();
                   
    }
}
catch (WebException apiException)
{
    string statusCodeMessage = apiException.Message;
               
}

 

PHP (Using JSON data type)

For PHP developers, we would suggest this article as a good tutorial on making all types of REST based requests in PHP: http://www.gen-x-design.com/archives/making-restful-requests-in-php/

 

 <?php

// This is provided as an example only with no warranties. This is for development purposes only and should not be used directly in a production environment

$newuserName = "YOUR USER NAME";
$locationName = "YOUR LOCATION NAME";
$accountLogin = "YOUR ACCOUNT LOGIN";
$platoName = "AN ADMINISTRATOR PLATO NAME";
$password = "THE PASSWORD";

$currentEpochDateInMS = time() * 1000;

// The numeric portion of the date should be represented in the epoch format
$data = array(
       "ActivationDate" => "/Date({$currentEpochDateInMS})/",
       "FirstName" => "YOUR FIRST NAME",
       "Grade" => 0,
       "LastName" => "YOUR LAST NAME",
       "PLATOName" => $newuserName,
       "Password" => "YOURPASSWORD",
       "SISId" => "123456789",
       "StateId" => "MN",
       "Status" => 1
);

$options = array(
       CURLOPT_URL => "https://api.nextple.platoweb.com/Location/{$locationName}/Learner",
       CURLOPT_POST => true,
       CURLOPT_POSTFIELDS => json_encode($data),
       CURLOPT_HTTPHEADER => array("Content-type: application/json"),
       CURLOPT_SSL_VERIFYPEER => false, // This ignores the SSL authority and should be changed in a production environment
       CURLOPT_USERPWD => "{$accountLogin}|{$platoName}:{$password}",
);

$ch = curl_init();

curl_setopt_array($ch, $options);

$output = curl_exec($ch);

$info = curl_getinfo($ch);

if ($output === false || $info['http_code'] != 200) {
       $output = "No cURL data returned [" . $info['http_code'] . "]";
       if (curl_error($ch)) {
              $output .= "\n" . curl_error($ch);
       }
}

echo $output;

 ?>
  • Was this article helpful?