XML API
From EFrontWiki
eFront provides an XML API for communicating with third-party applications.
The XML API is a request/response module which takes as input various requests (called actions) and outputs the corresponding responses formated in XML. A third-party application can access the XML API through the api.php eFront web page. All the requests and their arguments are passed as arguments in the api.php web page and the module response are outputed through this webpage. A common usage for the XML API is to allow SSO (Single Sign On) between eFront and other applications.
Following, all the supported actions as well as their arguments in v1.0 of the XML API module are described.
Contents |
[edit] Token Request
Action: token Arguments: ---
For a third-party application to use the XML API module, is necessary to identify itself and log into the system. For security reasons, the XML API module utilizes a token approach.
Whenever an application wants to communicate with the XML API module, it requests a token from the module. This token will be utilized through all the following requests, until it expires after 30minutes or the application explicitly logs out of the module. The generated tokens have a length of 30-chars and are stored along with their status (unlogged,logged) in the system's database.
An example of the usage of this action is the following:
http://efront/api.php?action=token
and a possible output is
<xml> <token>IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe</token> </xml>
[edit] Log-in into the module (API)
Action: login Arguments: token, username, password
For a third-party application to log-in into the XML API module, it is necessary to provide its token, and administrator's account login and password. The module checks the passed arguments and if they are correct, it responses a corresponding status, otherwise it responses the error description. In the case of correct log-in, the module updates the token's status to logged.
An example of the usage of this action is the following:
http://efront/api.php?action=login&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&username=abcd&password=efgsa
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>Invalid username/passord</message> </xml>
[edit] Log-in into platform (eFront)
Action: efrontlogin Arguments: token, login
In order to log-in into eFront via API, it is necessary to provide the token and the login of the account you want to login into platform. The module checks if the login exists and logs user into eFront, responsing also a corresponding status. Otherwise it responses the error description.
An example of the usage of this action is the following:
http://efront/api.php?action=efrontlogin&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=abcd
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>This user does not exist</message> </xml>
[edit] Create a new user
Action: create_user Arguments: login, password, name, surname, languages, email, token
After log-in, the third party application can fully use the module's actions. The most important action is the creation of a new user. The application must provide its token, the login and the password of the new user, his name and surname, his email and his language. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and creates the new user, otherwise it responses an error message.
An example of the usage of this action is the following:
http://mydomain.com/efront/www/api.php?action=create_user&login=newlogin&password=newpwd&name=Michael& surname=Smith&email=michale@smith.com&languages=english&token=MhgqmL61hEJ2mMXSVi3rMr97S9WMpt
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User already exists</message> </xml>
[edit] Update an existing user
Action: update_user Arguments: login, password, name, surname, email, token
Using this action, the application can update the password, name and surname of an existing user. The application must provide its token, the login of the existing user, his new password, his new name and his new surname. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and updates the user, otherwise it responses an error message.
An example of the usage of this action is the following:
http://mydomain.com/efront/www/api.php?action=update_user&login=newlogin&password=newpwd &name=Michael&surname=Smith&email=michale@smith.com&token=MhgqmL61hEJ2mMXSVi3rMr97S9WMpt
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Activate a user
Action: activate Arguments: token, login
Another provided action is the activation of an existing user. The application must provide its token and the login of the user to be activated. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and activates the corresponding user.
An example of the usage of this action is the following:
http://efront/api.php?action=activate&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Deactivate a user
Action: deactivate Arguments: token, login
Another provided action is the deactivation of an existing user. The application must provide its token and the login of the user to be deactivated. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and deactivates the corresponding user.
An example of the usage of this action is the following:
http://efront/api.php?action=deactivate&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Remove an existing user
Action: remove_user Arguments: token, login
Another provided action is the removal of an existing user. The application must provide its token and the login of the user to be deleted. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and removes the corresponding user.
An example of the usage of this action is the following:
http://efront/api.php?action=remove_user&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Assign lesson to user
Action: lesson_to_user Arguments: token, login, lesson
Another provided action is the assignment of a lesson to a user. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and assigns the corresponding lesson to the user
An example of the usage of this action is the following:
http://efront/api.php?action=lesson_to_user&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john&lesson=4
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Remove a lesson from user
Action: lesson_from_user Arguments: token, login, lesson
Another provided action is the de-assignment of a lesson to a user. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and deassigns the corresponding lesson to the user
An example of the usage of this action is the following:
http://efront/api.php?action=lesson_from_user&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john&lesson=4
and a possible output is:
<xml> <status>ok</status> </xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] Lesson info
Action: lesson_info Arguments: token, lessons
Another provided action is the request of general information about a lesson. The application must provide its token and the id of the lesson. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and provides general information about the corresponding lesson
An example of the usage of this action is the following:
http://efront/api.php?action=lesson_info&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&lesson=3
and a possible output is:
<xml>
<general_info>
<name>High-Speed networks</name>
<direction>Networks</direction>
<price>450$</price>
<language>english</language>
</general_info>
</xml>
or
<xml> <status>error</status> <message>Lesson doesn't exist</message> </xml>
[edit] User info
Action: user_info Arguments: token, login
Another provided action is the request of general information about a lesson. The application must provide its token and the login of the user. The module checks whether the provided token is valid and whether its status is logged. If so, it processes the request and provides general information about the corresponding user
An example of the usage of this action is the following:
http://efront/api.php?action=user_info&token=IQwwIuvXlLbwjjNXNf7XHMJh2DfBEe&login=john
and a possible output is:
<xml>
<general_info>
<name>John Joss</name>
<active>1</active>
<user_type>professor</user_type>
</general_info>
</xml>
or
<xml> <status>error</status> <message>User doesn't exist</message> </xml>
[edit] API Demo
In order for a non-expert user to become familiar with eFront's XML API, we have created a demo page that demonstrates all the supported API functions along with their arguments and output. The page is called "apidemo.php" and is located in the root directory of eFront's installation. Note that that page is fully functional (e.g the actions are indeed executed), so it can also be used as front-end for utilizing the XML API.
 API Demo page |
 API Demo page |
