Api

From Growth Engineering
Jump to: navigation, search

Growth Engineering API gives exposure to the applications functionality. This is a full specification on how external developers can interact with the application.


Contents

Overview

The Growth Engineering API has been designed as a Representational state transfer (REST) model, which utilizes Hypertext Transfer Protocol (HTTP) methods. API requests are made through HTTP methods, such as; GET, POST, DELETE. All required functions are manipulated through these methods, which are compatible across all browsers.

For reliability, the API restricts the external developer to one data type, JavaScript Object Notation (JSON). API requests must be JSON. Any other data types, such as XML, will be rejected. API responses will also be JSON. JSON offers a flexible means for developers to interact with the API, through a multitude of programming languages, such as; PHP, Python, Ruby.

Authenticated developers will only have access to the limited resources available through the API. Authentication is done through a modified version of OAuth 1.0.

From a design perspective, the API is divided into 4 accessible modules; Users, Courses, Invites and Reports. The entire functionality of the LMS can be mapped from these, with exception to end-user interactions. Users can be created, updated, and deleted from one resource. The same can be done to Courses and Invites. An authenticated user can apply CRUD principles to these three modules, giving them full control of data. Reporting is read-only, and poses the highest strain on resources. Results can yield thousands of results, depending on the parameters of the JSON. Reporting is limited to 100 results, with optional parameters to paginate these results to increase the limit.

Authentication

Requests are permitted only to users that have authenticated with the API. The authentication process creates a session which will have a decaying life cycle. The time will be refreshed to its original time with each API request, thus confirming the connection is active, and in use.

Authentication comprises of 3 tokens; a Client ID, a Secret key, and an Access token. The Client ID and Secret key will be supplied. Both parties will be aware of these tokens. The Client ID will be passed over HTTP. Secret key remains secret, and won't be passed over HTTP. The Access token is a randomly generated value comprising of alpha-numeric characters. This is generated on a users first call to the API. Authentication is determined by comparing a SHA-1 hash of the Access token, and Secret key, which would have been concatenated. If the match is successful, you are given a Session ID, which will be used as a reference for each subsequent request.

Session ID's are given a time limit, which is refreshed with each API request. This expiry time is used to gauge activity, and end the session after prolonged inactivity. In the event of a session exceeding its expiration time, the session will end, and the user will be forced to re-authenticate.

Example Request

PHP

session_start();
 
$client_key = "hgi4dk2A";              // Supplied by us, passed over HTTP
$secret_key = "u6udnto4AFsaw24";       // Supplied by us, never passed over HTTP
 
$authorised = isset($_SESSION['session_token']);
 
if(!$authorised) {
 
	$has_token = isset($_SESSION['access_token']);
 
	if(!$has_token) {
 
		$curl = curl_init();
		curl_setopt_array($curl, array(
	             CURLOPT_RETURNTRANSFER => 1,
       		     CURLOPT_URL => 'http://www.growthacademy.co.uk/api/auth/get_token.php?client_key='.$client_key
		));
 
		$response = curl_exec($curl);
		curl_close($curl);
		if($response) {
			$_SESSION['access_token'] = $response;
		}
		echo $response;	
	}
 
	$token = $_SESSION['access_token'];
	if(!$token) { die("error"); }
 
	$hash = sha1($token.$secret_key);
	$post_array = array("hash" => $hash, "client_key" => $client_key);
 
	$curl = curl_init();
	curl_setopt_array($curl, array(
		CURLOPT_RETURNTRANSFER => 1,
		CURLOPT_URL => 'http://www.growthacademy.co.uk/api/auth/authenticate.php',
		CURLOPT_POST => 1,
		CURLOPT_POSTFIELDS => $post_array
	));
 
	$response = curl_exec($curl);
	curl_close($curl);
	echo $response;
 
	$_SESSION['session_token'] = $response;
}
?>

The authenticated session is limited to a single IP address. This ensures that session hijacking is prevented by external users. Once a session has been created, this must be called for every request. This is done via a query string for a resource.

$session_token = $_SESSION['session_token'];
 
'http://www.growthacademy.co.uk/api/users?session_token='.$session_token

REST API Methods

JSON Object Structure

The JSON, or JavaScript Object Notation is standardized for compatibility with API requests that are made. JSON responses will be a consistent structure, so external developers can deal with the object.

Data types and syntax remain the same, using numbers, strings, booleans, arrays and objects. The following example uses a combination of these data types; a standard JSON object that can be sent as an API request.

{
   "id": 24,
   "first_name": "Joe",
   "last_name": "Bloggs",
   "roles": [2, 3],
   "username": "joebloggs",
   "password": "jb123",
   "active": true
}

Each method differs in its request acceptance. GET methods will pass JSON objects via a query string. The parameter name is important to identify the module used, ie:

<?php
 
   $data = array("user_id" => 635);
   $json = json_encode($data);
 
   'http://www.growthacademy.co.uk/api/users?object='.$json;
 
?>

POST methods require an Array to be passed, with the value being the JSON object. Array's can be created with parameters needed, and encoded to a JSON object afterwards. The following example is a user creation object. The encoded object can then be sent as a request.

<?php
 
   $data = array("first_name" => "Joe", "last_name" => "Bloggs", "email" => "joe.bloggs@example.com", "username" => "joebloggs1", 
                       "password" => "jb123", "team_id" => 24, "group_id" => "", "role" => array(2,3), "set_active" => "yes");
 
   $json_object = array("user" => json_encode($data));
 
?>

Users

GET /users

This method takes a JSON object as a parameter, and returns a JSON object. If an invalid JSON object is given, or no results are found, an error is returned.

This method is a search on all users for the platform, based on search parameters.

Resourse URL

http://www.growthacademy.co.uk/api/users/

Parameters

id
When set, returns the users data that matches the specified 'id'.
Example Value: 123
first_name
When set, returns user data that matches the specified 'first_name'. Parameter isn't case senstivie..
Example Value: "Joe"
last_name
When set, returns user data that matches the specified 'first_name'. Parameter isn't case senstivie..
Example Value: "Bloggs"
username
When set, returns user data that matches the specified 'first_name'. Parameter isn't case senstivie..
Example Value: "JBloggs"
team_id
Takes a comma separated string of integers, an array of integers or a single integer value. When set, searches for users matching all parameters specified.
Example Value(s): [24,56,59], "24, 56, 59", 24
group_id
Takes a comma separated string of integers, an array of integers or a single integer value. When set, searches for users matching all parameters specified.
Example Value(s): [19, 44], "19, 44", 44
role_array
Takes a comma separated string of integers, an array of integers or a single integer value. When set, searches for users matching all parameters specified.
Example Value(s): [2,3], "2, 3", 3
paginate
Takes an array of 2 parameters; first parameter is the amount of rows to return, second parameter is the page of the returned rows (assuming the amount of results returned is greater than the first parameter of this array), to view.
Example Value: [200, 2]

Example Request

PHP

An example request for searching for a user via CURL.

<?php
 
   $data = array("first_name" => "Joe", "last_name" => "Bloggs", "paginate" => array(100, 1));
 
   $json_object = json_encode($data);
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/users?session_token='.$session_token.'&object='.$json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>


Example Response

An example response for a valid user found.

[
  {
    "status": "success",
    "code": 3000,
    "message": "Action Successful",
    "rows_returned": 1,
    "response":
    [
      {
        "user_id": 123,
        "first_name": "Joe",
        "last_name": "Bloggs",
        "username": "JBloggs",
        "password": "JB123",
        "division": "UK",
        "region": "London",
        "branch": "HR",
        "team": "Team 1",
        ... : ...
      }
    ]
  }
]

POST /users

POST handles the creation of a new user, and updating an existing user. The syntax of the JSON will define which of these processes is done. The majority of user data is required, in addition to a limited set of optional parameters. User characteristics are required, such as name, username, and password. Requirements on the LMS side, are details concerning account type (roles), team hierarchies, direct manager (if the user is a Learner), and learning group identification.

Resourse URL

http://www.growthacademy.co.uk/api/users/

Parameters

user_id (optional)
If set, the POST is registered as an update. The subsequent parameters will be used to update an existing record, of the matching user_id. If no user_id is found, an error message will be returned. If the parameter isn't set, the POST registers as a create.
Example Value: 123
first_name
First name of the desired user. Input is case-sensitive.
Example Value: "Joe"
last_name
Last name of the desired user. Input is case-sensitive.
Example Value: "Bloggs"
username
Username of the desired user. Input is case-sensitive. This remains unchanged for the life span of the account.
Example Value: "JBloggs"
password
Password of the desired user. Maximum of 24 characters, any combination of upper-case, lower-case and numeric. The inclusion of symbols will result in an error response. All passwords are encoded with a SHA-1 hash.
Example Value: "jb123"
email
Email address of the desired user. Must be of valid syntax, or an error response will be returned.
Example Value: "joe.bloggs@example.com"
team_id
Corresponds to the hierarchy team the desired user will enter.
Example Value: 321
group_id
Corresponds to content distribution. Content can be allocated to individual groups, users can be placed into relevant groups.
Example Value: 213
role_array
Integer values represent different roles. Each have different access rights and permissions. A combination of roles are permitted. Role request must be defined in an array.
1 - Admin - Has access to all functionality. Can manage users, teams, groups and content.
2 - Manager - Manage users within this managers team. Cannot create, modify, or delete any users outside of the managers team.
3 - Learner - Has access to allocated and open access content. Learner accounts can only progress through content.
4 - Expert - An expert is used to answer general questions from learners. A good knowledge of the platform is required.
5 - Assessor - Assessors evaluate markable content from learners, and determine whether its a pass or fail.
6 - Tutor - Specific to classroom bookings.
7 - Demo Account - Demo accounts are given restricted access. They can view designated demonstration content. This content isn't evaluated in any way.
Example Value: 2,3
set_active (optional)
When set, determines if the user account created will be set online or offline. If unset, the default value will be set to online.
Example Value: online

Example Request

PHP

An example request for creating a user using CURL.

<?php
 
   $data = array("first_name" => "Joe", "last_name" => "Bloggs", "email" => "joe.bloggs@example.com", "username" => "joebloggs1", 
                       "password" => "jb123", "team_id" => "", "group_id" => "", "role" => array(2,3), "set_active" => "yes");
 
   $json_object = array("user" => json_encode($data));
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/users?session_token='.$session_token,
       CURLOPT_POST => 1,
       CURLOPT_POSTFIELDS => $json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Example Response

An example response for creating a user.

[
  {
    "status": "success",
    "code": 1000,
    "message": "Action Successful",
    "userdata":
    {
        "first_name": "Joe",
        "last_name": "Bloggs",
        "email": "joe.bloggs@example.com",
        "username": "joebloggs1",
        "password": "jb123",
        "team_id": "",
        "group_id": "",
        "role": [2,3],
        "set_active": "yes"
    }
  }
]

Example Request

PHP

An example request for updating a user using CURL.

<?php
 
   $data = array("id" => "1", "first_name" => "Joe", "last_name" => "Bloggs", "email" => "joe.bloggs@example.com", "username" => "joebloggs1", 
                          "password" => "jb123", "team_id" => "", "group_id" => "", "role" => array(2,3), "set_active" => "yes");
 
   $json_object = array("user" => json_encode($data));
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/users?session_token='.$session_token,
       CURLOPT_POST => 1,
       CURLOPT_POSTFIELDS => $json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Example Response

An example response for updating a user.

[
  {
   "status": "success",
   "code": 1000,
   "message": "Action Successful",
   "userdata":
    {
     "user_id": 1,
     "first_name": "Joe",
     "last_name": "Bloggs",
     "email": "joe.bloggs@example.com",
     "username": "joebloggs1",
     "password": "jb123",
     "team_id": "",
     "group_id": "",
     "role": [2,3],
     "set_active": "yes"
    }
  }
]

DELETE /users

This method takes a JSON object which includes a user ID, and returns a JSON object.

Resourse URL

http://www.growthacademy.co.uk/api/users/

Example Request

PHP

An example request for deleting a user using CURL.

<?php
 
   $data = array("user_id" => "1");
 
   $json_object = json_encode($data);
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/users?session_token='.$session_token.'&object='.$json_object  
       CURLOPT_CUSTOMREQUEST => 'DELETE'
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Courses

GET /courses

This method takes a parameter, and returns a JSON object. Courses is used for end users to get course IDs and details.

Resource URL

http://www.growthacademy.co.uk/api/courses/

Parameters

types
This parameter lists all the available object types. These object types are needed for inviting users to content, or for finding details on a specific type - will be used with an object ID or search string.

Example Request

PHP

An example request for searching for course types using CURL.

<?php
 
   $data = array("courses" => "types");
 
   $json_object = json_encode($data);
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/courses/?object='.$json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Example Response

An example response.

[
  {  
   "types" : [
       "assessment", 
       "test", 
       "elearning", 
       "devstream", 
       "survey", 
       "review", 
       "material"
    ]
  }
]


search
This GET method takes a JSON object, which will contain parameters on which to search. Successful objects, will return a JSON object containing relevant data. Parameters:
type (required) - From the results of the GET method 'types', choose an object type for searching.
head_title (optional) - Compares the value to possible matches of the object.
object_id (optional) - Searches for a specified object type with the object ID given.
Example: http://www.growthacademy.co.uk/api/courses/


Example Request

PHP

An example request for searching for a course using CURL.

<?php
 
   $data = array("type" => "assessment", "head_title" => "sales");
 
   $json_object = json_encode($data);
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
      CURLOPT_RETURNTRANSFER => 1,
      CURLOPT_URL => 'http://www.growthacademy.co.uk/api/courses/?object='.$json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Example Response

An example response for searching for a course.

[
  {
   "id": 14,
   "head_title": "Sales Operations",
   "description": "Brief overview of sales operations in practical situations",
   "status": "Y",
   "launch": "Y",
   "...": "..."
  }, 
  {
   "id": 22,
   "head_title": "Approaching salesmen",
   "description": "Top tips on negotiating with Salesmen",
   "status": "Y",
   "launch": "Y",
   "...": "..."
  }
]

Invites

GET /invites

This method takes a JSON object as a parameter, and returns a JSON object. If an invalid JSON object is given, or no results are found, an error response is returned.

Resource URL

http://www.growthacademy.co.uk/invites/

POST /invites

This method takes a JSON object as a parameter, and returns a JSON object. If an invalid JSON object is given, or no results are found, an error is returned.

POST handles the creation of an invite, for a specified user. The JSON object will have required parameters to create a successful invite. A user ID, object type and object ID will be needed...

Resource URL

http://www.growthacademy.co.uk/api/invites/

Parameters

user_id
When set, this is the specific user which will be subject to an invitation. If an invalid, or non-existent ID is specified, an error response is given.
Example Value: 123
object_type
When set, this is the specified object type on which an object ID will refer too.
Example Value: assessment
object_id
When set, this is the object which the user will be invited to.
Example Value: 123
overwrite
When set, this will overwrite any outstanding invite to the specified object. When unset, this value will default to false, and won't overwrite the invite.
Example Value: true
send_confirmation
When set, this will send a confirmation email to the specified user with details on the invited object. When unset, this value will default to false, and won't send email confirmation to this user.
Example Value: true

Example Request

PHP

An example request for inviting a user to a learning object using CURL.

<?php
 
   $data = array("user_id" => 123, "object_type" => "assessment", "object_id" => 1, "attempt" => 1, "expiry" => "2020-01-31");
 
   $json_object = array("invite" => json_encode($data));
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/invites/',
       CURLOPT_POST => 1,
       CURLOPT_POSTFIELDS => $json_object
   ));
 
   $response = curl_exec($curl);
 
   curl_close($curl);   
 
?>


Example Response

An example response for inviting a user to a learning object.

[
  {
   "status": "success",
   "code": 1000,
   "message": "Action Successful",
   "invite_data":
    {
     "invite_id": 536,
     "user_id": 123,
     "object_type": "assessment",
     "object_id": 1,
     "head_title": "Introduction to Objections",
     "description": "",
     "attempts": 1,
     "expiry": "2020-01-31"
    }
  }
]

DELETE /invites

Report

GET /report

This method takes a JSON object as a parameter, and returns a JSON object. If an invalid JSON object is given, or no results are found, an error is returned.

Resource URL

http://www.growthacademy.co.uk/api/report/

Parameters

user_id
When set, specifies the user in which to run a report on. user_id is the main search parameter. If set with either first_name, or last_name, it will take a combination of these search terms. For example, a user with the ID '2', and last name 'Bloggs'.
Example Value: 24
first_name
When set, runs a report on all users that have a matching first name to the search parameter.
Example Value: "Joe"
last_name
When set, runs a report on all users that have a matching last name to the search parameter.
Example Value: "Bloggs"
object_type
When set, will search of the specified object type (see /GET courses). If unset, it will run a search on all object types. (Note, this could increase execution time).
Example Value: "test"
object_id
When set, will search for the specified ID. Will only return a result, if object_type is set.
Example Value: 2
start_date
When set, specifies the starting date on which to run the report. If unset, default date is defined as the current day.
Example Value: "2013-01-01"
end_date
When set, specifies the ending date on which to run the report. If unset, default date is defined as the current day.
Example Value: "2013-03-30"
mode
When set, determines what data to search. Searchable data consists of completed, or outstanding learning objects. If unset, data returned will be for both outstanding and completed learning objects.
Example Value: "outstanding"

Example Request

PHP

An example request for reporting on a user using CURL

<?php
 
   $data = array("user_id" => , "object_type" => , "start_date" => "2013-01-01", "end_date" => "2013-04-20");
 
   $json_object = json_encode($data);
 
   $curl = curl_init();
 
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_URL => 'http://www.growthacademy.co.uk/api/report/?report='.$json_object
   ));     
 
   $response = curl_exec($curl);
 
   curl_close($curl);
 
?>

Example Response

An example response for reporting on a user.

[
 {
  "status": "success",
  "code": 1000,
  "message": "Action Successful",
  "report_data":
   [ 
     {
       "user_id": 1,
       "object_type": "assessment",
       "object_id": 24,
       "head_title": "Annual Appraisal",
       "complete_date": "2013-03-30",
       "score": "100%",
       "object_data" : [
         {
           "question_text": "Have they performed to the best of their ability?",
           "question_type": "multi_a_e",
           "correct_answer": "D",
           "given_answer": "D",
           "score": "100%",
           "comments": ""
         },
         {
           "question_text": "What new skills have they learnt?",
           "question_type": "text",
           "correct_answer": "",
           "given_answer": "Platform knowledge greatly improved",
           "score": "100%",
           "comments": "Excelled in performance"
         },
         {
           "question_text": "Overall Performance?",
           "question_type": "1-5",
           "correct_answer": "5",
           "given_answer": "5",
           "score": "100%",
           "comments": "Outstanding"
         }
       ]
     },
     {
       "user_id": 1,
       "object_type": "assessment",
       "object_id": 4,
       "head_title": "Pipeline Qualifications",
       "complete_date": "2013-04-04",
       "score": "100%",
       "object_data" : [
         {
           "question_text": "Do we have a viable solution that meets the identified needs of the customer?",
           "question_type": "1-5",
           "correct_answer": "5",
           "given_answer": "5",
           "score": "100%",
           "comments": ""   
         },   
         {
           "question_text": "Does it fit within their budget?",
           "question_type": "1-5",
           "correct_answer": "5",
           "given_answer": "5",
           "score": "100%",
           "comments": ""   
         },
         {
           "...":"..."
         }   
       ]
     }
   ]
 }
]

Response Codes

Response codes will be given with each API request. A brief response message will be given as part of the JSON object response, and a more detailed overview of the request will be given here.