VenU Web Service API

The VenU Web Service API allows external applications access to query, update and delete data within our Learning Management System.

The API is based on REST principles, which makes it very easy to write and test applications. You can use your browser to access URLs, and you can use virtually any HTTP client, in any programming language, to interact with it.
Unlike SOAP, the REST architecture does not require XML parsing, or to pass around message headers, and this ends up in using less bandwidth. The error handling also differs, since it follows the HTTP 1.1 Specification, making it more accessible and easier to use on more devices and platforms.

After a LMS is created, VenU will work with the client to design a custom API that will meet their specific business requirements. We will provide a set of URIs that will return data in either the JSON or XML format, and how frequently you can query them will depend on the data being retrieved and the specific server configuration that the LMS is hosted on. The web service is run using the HTTP protocol and supports the GET, PUT, POST, and DELETE methods.

The client can be written in any programming language that supports the following:

• can communicate with the HTTP protocol (using GET, PUT, POST and DELETE methods)
• can communicate over SSL (typically this requires OpenSSL support)
• can use one of the supported Authentication methods
• can parse the returned data (either JSON or XML)

In a LAMP environment, this can be achieved using the following technologies:

• PHP 5.3.3+ compiled with the cURL extension
• A recent version of cURL 7.19.7+ compiled with OpenSSL and zlib

We have the ability to configure the API in many ways. These settings will be set based on your business and security requirements, and any changes must be discussed with VenU before they can be applied to your web service (the changes will be applied to wsapi-config.php).

Our web service supports the CORS standard and this is implemented by the Allow Cross-Origin and Allowed Domains configuration settings.

We currently support two authentication methods, either PBKDF2 or Basic Authentication. These methods are based on industry best practices, and which one you choose depends on your security requirements and the libraries available to your application.

This method is very similar to Basic Authentication, but the difference being the password is sent as a hash, instead of plain text.
Since we do require all web service calls to be made over SSL then Basic Authentication could be used a fallback option if this method is too complicated or resource intensive for the client.

Here are the steps required to implement the PBKDF2 method (replace all <> values, including the brackets):

1. client generates a PBKDF2 hash using the following values
   • algorithm = set to the value for Encryption Method (defaults to sha256, but this can be changed)
   • private key = set to the value for Private Key (will be supplied by VenU)
   • salt = admin@<client-lms-domain> (Ex. admin@ven-u.com)
   • iterations = 1024 (can be changed if needed, more iterations is more secure, but also slower)
   • length = set to the value for Signature Length
2. client sends the following header in every request
   • X-Authorization: <hash>=&&=<salt>
3. web service generates a PBKDF2 hash using the same values and the supplied salt
4. web service compares it's hash to the one sent and if they match then the call is authenticated
5. web service will proceed with the request and return the requested data

The web service handles errors using the HTTP 1.1 Specification for Status Codes. These errors can be returned by the server or, at the application level, by the API.
They should be handled differently in each case, because they will be returned in different formats and have different meanings.

URI Structure

The URIs are structured in the following way:

https://<url>/<object>/<method>/<identifier or field>/

HTTP Server Error

When an error is returned by the server, it is returned as a HTTP Response Header, like shown below:

HTTP/1.1 404 Not Found

Here are the common reasons for getting an error from the server:

Please remember to add a trailing slash to the end of all URIs.

Application Error

All errors at the application level will be returned with the following HTTP Response Header, and the response will include an error message.

HTTP/1.1 200 OK