2a7e571edc
* Change all folders and file names * Change string in all files FEA: ItEr75S03CommunityMaterial
177 lines
4.7 KiB
Text
177 lines
4.7 KiB
Text
Web Services
|
|
============
|
|
|
|
.. sectnum::
|
|
|
|
:Author: Manuel Rego Casasnovas
|
|
:Contact: rego@igalia.com
|
|
:Date: 28/06/2011
|
|
:Copyright:
|
|
Some rights reserved. This document is distributed under the Creative
|
|
Commons Attribution-ShareAlike 3.0 licence, available in
|
|
http://creativecommons.org/licenses/by-sa/3.0/.
|
|
:Abstract:
|
|
Basic documentation about LibrePlan web services usage.
|
|
|
|
|
|
.. contents:: Table of Contents
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Inside ``scripts/rest-clients/`` folder of LibrePlan source code, you can find
|
|
several scripts to test LibrePlan web services. There are web services for
|
|
most import entities in the application. And if needed more could be easily
|
|
developed.
|
|
|
|
All *integration entities* (LibrePlan entities that can be exported and/or
|
|
imported) has a common attribute called ``code``. This field would be the one
|
|
used to share information between LibrePlan and other systems or other LibrePlan
|
|
instances.
|
|
|
|
LibrePlan web services are REST based. But, they are just using two HTTP
|
|
methods with the following meaning:
|
|
|
|
* ``GET``: Used to extract information from LibrePlan. For each case they will
|
|
return a list with all the entities. For example, resources web service will
|
|
return a list with all application resources.
|
|
|
|
You can also pass ``code`` attribute (since LibrePlan 1.2) in order to return
|
|
just one entity sending the code as a GET parameter.
|
|
|
|
* ``POST``: Used to add and update information in LibrePlan. These services will
|
|
receive a XML file with a list of entities. For each entity there could be 2
|
|
different cases:
|
|
|
|
* If it already exists: Update entity with new data.
|
|
* If it does not exist: Add the new entity.
|
|
|
|
These means that delete is not allowed from web services, in that way only new
|
|
info could be added or updated. This is because of entities are related with
|
|
others and remove operation could be dangerous. Then if necessary, the
|
|
recommendation would be add a field to disable such entity.
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
These scripts are written in bash so you need to be running a bash terminal to
|
|
use them.
|
|
|
|
Moreover, it is recommended to have Tidy available in your system. You can
|
|
install it with the following command in Debian based distributions::
|
|
|
|
# apt-get install tidy
|
|
|
|
In openSUSE with::
|
|
|
|
# zypper install tidy
|
|
|
|
Or in Fedora with::
|
|
|
|
# yum install tidy
|
|
|
|
|
|
Default credentials
|
|
-------------------
|
|
|
|
In order to test these scripts you will need an user with reader and writer
|
|
permissions for web services of LibrePlan. Default credentials are:
|
|
|
|
* Reader permission:
|
|
|
|
* User: ``wsreader``
|
|
* Password: ``wsreader``
|
|
|
|
* Writer permission:
|
|
|
|
* User: ``wswriter``
|
|
* Password: ``wswriter``
|
|
|
|
.. NOTE::
|
|
|
|
LibrePlan web services use `HTTP Basic Authentication`_
|
|
|
|
|
|
Common parameters
|
|
-----------------
|
|
|
|
There are already defined several parameters to be used in the scripts to define
|
|
the server to execute the tests:
|
|
|
|
Demo environment (``without parameters``) - default
|
|
|
|
Use server where demo is launched using the following URL:
|
|
``http://demo.libreplan.org/libreplan-demo/``
|
|
|
|
Example::
|
|
|
|
$ ./export-resources.sh
|
|
|
|
Production environment (``--prod``)
|
|
|
|
Use server deployed with Tomcat in a production deployment in the following
|
|
URL: ``http://localhost:8080/libreplan/`` (the installation done by Debian
|
|
package).
|
|
|
|
Example::
|
|
|
|
$ ./export-resources.sh --prod
|
|
|
|
Development environment (``--dev``)
|
|
|
|
Use server deployed with Jetty during development in the following URL:
|
|
``http://localhost:8080/libreplan-webapp/``
|
|
|
|
Example::
|
|
|
|
$ ./export-resources.sh --dev
|
|
|
|
|
|
XML Schemas
|
|
-----------
|
|
|
|
To get XML schema use the following script::
|
|
|
|
$ get-xml-schema.sh <service-path>
|
|
|
|
Example::
|
|
|
|
$ get-xml-schema.sh resources
|
|
|
|
|
|
Export scripts
|
|
--------------
|
|
|
|
There several scripts to just get information from LibrePlan system. They always
|
|
start with ``export-`` prefix. These scripts usually don't need any parameter
|
|
(apart from the one to select the environment). They will return a XML output
|
|
with the data requested.
|
|
|
|
Example::
|
|
|
|
$ ./export-resources.sh
|
|
|
|
To export just one specific resource by code you can add a new extra parameter.
|
|
Example::
|
|
|
|
$ ./export-resources.sh WORKER00011
|
|
|
|
|
|
Import scripts
|
|
--------------
|
|
|
|
As for the previous point, in order to insert data in LibrePlan system thought
|
|
web services there are several scripts with prefix ``import-``. In this case,
|
|
these scripts need a special parameter, that would be a XML file with data to be
|
|
inserted in LibrePlan. There are usually files with ``-sample`` suffix as
|
|
example data. Again, output for these scripts is a XML message with the possible
|
|
errors trying to insert the data in the system.
|
|
|
|
Example::
|
|
|
|
$ ./import-resources.sh resources-sample.xml
|
|
|
|
|
|
.. _`HTTP Basic Authentication`: http://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
|