Web services / APIv1

Note: the webservices listed below are now deprecated. Please check Rest-WebServices for updated web services on Chamilo 1.11.*.

Introduction

The following documentation gives a description (although somewhat outdated) of the behaviour of the Chamilo Web Services. In this APIv1, mostly focused on administrative actions, we use SOAP as a Web Service application protocol (although it would be easy to extend to other protocols). As such, all communication should be sent using SOAP headers and received using a SOAP parser.

An APIv2 is also available (but not yet documented) only for basic webservices in main/webservices/api/v2.php. This API works in REST and serves to feed the mobile application of Chamilo.

If you want to know about more Chamilo web services, please check the main/webservices/ folder in Chamilo. Many scripts are available there for your use as API.

Web services for Chamilo 1.9 and later

Web services as documented below are available since version 1.9 of Chamilo.

Authentication

The 'secret_key' is a mandatory parameter to connect to the web services. It is composed of the $_configuration['secret_key'] value inside of the LMS's main/inc/conf/configuration.php file (which can be changed at will, as it is only used for web services at the time of writing) and the IP address of the caller.

For example, if I am calling the webservice from an IP address of 134.23.25.34, I will have to generate an SHA1 encrypted string from this IP addess with the secret key. This can be done for example, in PHP, through the command:

$security_key = 'abcdef1234567890';
$ip_address = '134.23.25.34';
$secret_key = sha1($ip_address.$security_key);

The $secret_key variable must be added manually to the Web Service caller script. It acts as a shared key. Please note that, with the shared key, any attacker could do serious damage to your web server through web services. Keep this key safe!

Calling the SOAP web services scripts is generally done through a URL of this kind: https://campus.chamilo.org/main/webservices/registration.soap.php. You can check the list of available functions through a call to https://campus.chamilo.org/main/webservices/registration.soap.php?wsdl

The caller IP

Getting the right IP address can sometimes be tricky. This should be the public IP address of the server calling Chamilo web services, or at least it should be the IP address as the Chamilo server sees it.

You can check how your IP is detected by the server, calling the http://campus.chamilo.org/main/webservices/testip.php script. The first line can be cut and used as the IP address to put in the $ip_address variable above (just remove the end-of-line character at the end of the first line).

External identifiers

For most Web Services provided, an identifier and a value are expected by Chamilo. For example, if you import your users from an Oracle database, you might use a unique ID coming from the LUSERID field and worth 1504. When calling Chamilo, we assume you will give us the user ID as you know it in your system.

That is, we expect you'll give us LUSERID as the user_id_field_name parameter, and 1504 as the user_id_value.

When you do that, Chamilo is able to find, inside its database, which user you are referring to, because Chamilo kept this reference (inside the extra_field_values table) when you created the user (or course, or session).

Available methods in registration.soap.php

registration.soap.php is the main web services script for APIv1. Although it's not the only one, it at least provides the following methods... (and probably a few more)

WSUser.DisableUser

Disables one user

Input

array(
 'secret_key' => 'abcdef1234567890',
 'user_id_field_name' => 'external_user',
 'user_id_value' => '1504',
);

Output

nothing (or error message)

WSUser.DisableUsers

Disables several users in one call.

Input

array(
'secret_key' => 'abcdef1234567890',
 array( 
  0=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1504'),
  1=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1582'),
 )
);

Output

array(
  0=>array('code'=>0,'message'=>'Operation was successful'),
  1=>array('code'=>0,'message'=>'Operation was successful'),
);

WSUser.EnableUser

Enables one user

Input

array(
 'secret_key' => 'abcdef1234567890',
 'user_id_field_name' => 'external_user',
 'user_id_value' => '1504',
);

Output

nothing (or error message)

WSUser.EnableUsers

Enables several users in one call.

Input

array(
'secret_key' => 'abcdef1234567890',
 array( 
  0=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1504'),
  1=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1582'),
 )
);

Output

array(
  0=>array('code'=>0,'message'=>'Operation was successful'),
  1=>array('code'=>0,'message'=>'Operation was successful'),
);

WSUser.DeleteUser

Deletes one user

Input

array(
 'secret_key' => 'abcdef1234567890',
 'user_id_field_name' => 'external_user',
 'user_id_value' => '1504',
);

Output

nothing (or error message)

WSUser.DeleteUsers

Deletes several users in one call

Input

array(
'secret_key' => 'abcdef1234567890',
 array( 
  0=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1504'),
  1=>array('user_id_field_name' => 'external_user', 'user_id_value' => '1582'),
 )
);

Output

array(
  0=>array('code'=>0,'message'=>'Operation was successful'),
  1=>array('code'=>0,'message'=>'Operation was successful'),
);

WSUser.CreateUser

Creates one user

Input

array(
'secret_key' => 'xsd:string',
'firstname' => 'xsd:string',
'lastname' => 'xsd:string',
'status' => 'xsd:int',
'loginname' => 'xsd:string',
'password' => 'xsd:string',
'encrypt_method' => 'xsd:string',
'user_id_field_name' => 'xsd:string',
'user_id_value' => 'xsd:string',
'visibility' => 'xsd:int',
'email' => 'xsd:string',
'language' => 'xsd:string',
'phone' => 'xsd:string',
'expiration_date' => 'xsd:string',
'extras' => 'tns:extra_field[]'
);

Output

int new_user_id

WSUser.CreateUsers

Creates several users in one call.

Input

array(
 'secret_key' => 'xsd:string',
 array(
  0 => array(
   'firstname' => 'xsd:string',
   'lastname' => 'xsd:string',
   'status' => 'xsd:int',
   'loginname' => 'xsd:string',
   'password' => 'xsd:string',
   'encrypt_method' => 'xsd:string',
   'user_id_field_name' => 'xsd:string',
   'user_id_value' => 'xsd:string',
   'visibility' => 'xsd:int',
   'email' => 'xsd:string',
   'language' => 'xsd:string',
   'phone' => 'xsd:string',
   'expiration_date' => 'xsd:string',
   'extras' => 'tns:extra_field[]'
  ),
  1 => array(
   'firstname' => 'xsd:string',
   'lastname' => 'xsd:string',
   'status' => 'xsd:int',
   'loginname' => 'xsd:string',
   'password' => 'xsd:string',
   'encrypt_method' => 'xsd:string',
   'user_id_field_name' => 'xsd:string',
   'user_id_value' => 'xsd:string',
   'visibility' => 'xsd:int',
   'email' => 'xsd:string',
   'language' => 'xsd:string',
   'phone' => 'xsd:string',
   'expiration_date' => 'xsd:string',
   'extras' => 'tns:extra_field[]'
  )
 )
);

Output

array(
 0 => array(
  'result' => 'xxx',
  'user_id_value' => 1504,
  'user_id_generated' => 1
 ),
 1 => array(
  'result' => 'xxx',
  'user_id_value' => 1504,
  'user_id_generated' => 1
 ),
);

WSUser.EditUser

Edits one user

Input

Output

WSUser.EditUsers

Edits several users in one call.

Input

Output

WSCourse.DeleteCourse

Deletes one course

Input

Output

WSCourse.DeleteCourses

Deletes several courses in one call.

Input

Output

WSCourse.CreateCourse

Creates one course

Input

Output

WSCourse.CreateCourses

Creates several courses in one call.

Input

Output

WSCourse.EditCourse

Edits one course

Input

Output

WSCourse.ListCourses

Lists courses

Input

Output

WSCourse.SubscribeUserToCourse

Subscribes one user to one course

Input

Output

WSCourse.UnsubscribeUserFromCourse

Unsubscribes one user from one course.

Input

Output

WSCourse.GetCourseDescriptions

Gets the list of course descriptions.

Input

Output

WSCourse.EditCourseDescription

Edits one description of one course.

Input

Output

WSSession.CreateSession

Creates one session.

Input

Output

WSSession.DeleteSession

Deletes one session.

Input

Output

WSSession.EditSession

Edits one session.

Input

Output

WSSession.SubscribeUserToSession

Subscribes one user to one session.

Input

Output

WSSession.UnsubscribeUserFromSession

Unsubscribes one user from one session

Input

Output

WSSession.SubscribeCourseToSession

Subscribes one course to one session.

Input

Output

WSSession.UnsubscribeCourseFromSession

Unsubscribes one course from one session

Input

Output