trunk/services/README.txt

/**
 * Ce fichier permet de décrire l'utilisation des webservices pour l'application
 * openFoncier.
 *
 * @package openfoncier
 * @version SVN : $Id$
 *
 * @todo XXX Reprendre la rubrique "Utilisation des services REST avec curl en
 * ligne de commande" et détailler la rubrique "Description des services REST
 * openFoncier"
 */

#############
Services REST
#############

*********************************
Installation, paramétrage et test
*********************************

============================================
Configuration d'Apache pour utiliser RESTLER
============================================

Activer le mod_rewrite Apache
-----------------------------

Le module Apache mod_rewrite est un module qui permet la réécriture des URLs.
Pour utiliser RESTLER il faut que ce module soit activé. Pour ce faire ::

    $ a2enmod rewrite

Paramétrer le virtualhost
-------------------------

Ajouter les lignes suivantes dans le paramétrage du virtualhost souhaité ::

    RewriteEngine On
        RewriteCond %{REQUEST_URI} ^.*/openfoncier/services/(.*[^/])
    RewriteRule ^(.*)$ /var/www/openfoncier/services/rest_entry.php [QSA,L]

Dans la configuration de votre virtualhost penser à ce que les méthodes HTTP
nécessaires GET, PUT, POST, DELETE soient autorisées.

Redémarrer Apache
-----------------

Pour que les changements prennent effet il faut redémarrer le serveur Apache ::

    $ /etc/init.d/apache2 restart


============================================================
Utilisation des services REST avec curl en ligne de commande
============================================================

Pour envoyer une demande concernant les utilisateurs, avec curl et simple HTTP authetification, on fait :

- en cas de GET :
$ curl --user <username> -v http://<server>/<path_to>/services/utilisateurs/<ID>

Le '<ID>' doit etre remplace par l'ID d'un utilisateur, le '<server>' doit etre remplace par un server IP
ou un domain name, et '<path_to>' est le chemin, dans la hierarchie des fichiers, ou se trouve openfoncier. 

- en cas de POST :
curl --user <username> -v -H "Content-Type: application/json" -d '{"nom":"Thierry", "email":"[email protected]","login":"tehierry","pwd":"password","om_profil":"5","om_collectivite":"1","om_type":"db_type"}' -X POST  http://<server>/<path_to>/services/utilisateurs

- en cas de PUT:
$ curl --user <username> -v -H "Content-Type: application/json" -d '{"nom":"Changed_name"}' -X PUT  http://<server>/<path_to>/services/utilisateurs/<ID>

- en cas de DELETE:
$ curl --user <username> -v -X DELETE http://localhost/~mirna/head_openfoncier/services/utilisateurs/<ID>

En cas d'encryptage SSL des donnes, curl doit etre utilise avec l'option E comme par exemple :
$ curl -E /<path_to>/key_certificate.concat --cacert /<path_to>/self_signed_sertificate.crt -k -v -H --user <username> -v https://<server>/<path_to>/services/utilisateurs/<ID>

Le key_certificate.concat contient la cle avec le certificat colle a la fin de la cle.


*****************************************
Description des services REST openFoncier
*****************************************

=======================
Ressource 'maintenance'
=======================

Méthode POST
------------

Synchronisation des utilisateurs via LDAP
*****************************************

/services/maintenance

{
"module" : "user",
"data" : "NA"
}


Traitement des retours de consultation périmés
**********************************************

/services/maintenance

{
"module" : "consultation",
"data" : "NA"
}


=========================
Ressource 'consultations'
=========================

Méthode PUT
-----------

/services/consultations


====================
Ressource 'messages'
====================

Méthode POST
------------

/services/messages


================================
Ressource 'dossier_autorisation'
================================

Méthode PUT
-----------

/services/dossier_autorisation


Méthode GET
-----------

/services/dossier_autorisation

1	fmichon	753	/**
2			* Ce fichier permet de décrire l'utilisation des webservices pour l'application
3			* openFoncier.
4			*
5			* @package openfoncier
6			* @version SVN : $Id$
7	fmichon	755	*
8			* @todo XXX Reprendre la rubrique "Utilisation des services REST avec curl en
9			* ligne de commande" et détailler la rubrique "Description des services REST
10			* openFoncier"
11	fmichon	753	*/
12	mlimic	515
13	fmichon	753	#############
14			Services REST
15			#############
16	mlimic	515
17	fmichon	755	*********************************
18			Installation, paramétrage et test
19			*********************************
20
21			============================================
22	fmichon	753	Configuration d'Apache pour utiliser RESTLER
23	fmichon	755	============================================
24	mlimic	515
25	fmichon	753	Activer le mod_rewrite Apache
26	fmichon	755	-----------------------------
27	mlimic	515
28	fmichon	753	Le module Apache mod_rewrite est un module qui permet la réécriture des URLs.
29			Pour utiliser RESTLER il faut que ce module soit activé. Pour ce faire ::
30	mlimic	515
31	fmichon	753	$ a2enmod rewrite
32	mlimic	515
33	fmichon	753	Paramétrer le virtualhost
34	fmichon	755	-------------------------
35	fmichon	753
36			Ajouter les lignes suivantes dans le paramétrage du virtualhost souhaité ::
37
38	mlimic	541	RewriteEngine On
39	fmichon	753	RewriteCond %{REQUEST_URI} ^./openfoncier/services/(.[^/])
40			RewriteRule ^(.*)$ /var/www/openfoncier/services/rest_entry.php [QSA,L]
41	mlimic	515
42	fmichon	753	Dans la configuration de votre virtualhost penser à ce que les méthodes HTTP
43			nécessaires GET, PUT, POST, DELETE soient autorisées.
44	mlimic	515
45	fmichon	753	Redémarrer Apache
46	fmichon	755	-----------------
47	mlimic	515
48	fmichon	753	Pour que les changements prennent effet il faut redémarrer le serveur Apache ::
49	mlimic	515
50	fmichon	753	$ /etc/init.d/apache2 restart
51	mlimic	515
52
53	fmichon	755	============================================================
54	fmichon	753	Utilisation des services REST avec curl en ligne de commande
55	fmichon	755	============================================================
56	fmichon	753
57	mlimic	522	Pour envoyer une demande concernant les utilisateurs, avec curl et simple HTTP authetification, on fait :
58	mlimic	515
59	mlimic	522	- en cas de GET :
60			$ curl --user <username> -v http://<server>/<path_to>/services/utilisateurs/<ID>
61	mlimic	515
62	mlimic	522	Le '<ID>' doit etre remplace par l'ID d'un utilisateur, le '<server>' doit etre remplace par un server IP
63			ou un domain name, et '<path_to>' est le chemin, dans la hierarchie des fichiers, ou se trouve openfoncier.
64	mlimic	515
65	mlimic	522	- en cas de POST :
66			curl --user <username> -v -H "Content-Type: application/json" -d '{"nom":"Thierry", "email":"[email protected]","login":"tehierry","pwd":"password","om_profil":"5","om_collectivite":"1","om_type":"db_type"}' -X POST http://<server>/<path_to>/services/utilisateurs
67	mlimic	515
68	mlimic	522	- en cas de PUT:
69			$ curl --user <username> -v -H "Content-Type: application/json" -d '{"nom":"Changed_name"}' -X PUT http://<server>/<path_to>/services/utilisateurs/<ID>
70	mlimic	515
71	mlimic	522	- en cas de DELETE:
72			$ curl --user <username> -v -X DELETE http://localhost/~mirna/head_openfoncier/services/utilisateurs/<ID>
73	mlimic	515
74	mlimic	522	En cas d'encryptage SSL des donnes, curl doit etre utilise avec l'option E comme par exemple :
75			$ curl -E /<path_to>/key_certificate.concat --cacert /<path_to>/self_signed_sertificate.crt -k -v -H --user <username> -v https://<server>/<path_to>/services/utilisateurs/<ID>
76	mlimic	515
77	mlimic	522	Le key_certificate.concat contient la cle avec le certificat colle a la fin de la cle.
78	fmichon	753
79
80			*****************************************
81			Description des services REST openFoncier
82			*****************************************
83
84	fmichon	755	=======================
85	fmichon	753	Ressource 'maintenance'
86			=======================
87
88			Méthode POST
89			------------
90
91	fmichon	755	Synchronisation des utilisateurs via LDAP
92			*****************************************
93
94	fmichon	753	/services/maintenance
95
96			{
97			"module" : "user",
98			"data" : "NA"
99			}
100
101
102	fmichon	755	Traitement des retours de consultation périmés
103			**********************************************
104
105			/services/maintenance
106
107	fmichon	753	{
108			"module" : "consultation",
109			"data" : "NA"
110			}
111
112
113	fmichon	755	=========================
114	fmichon	753	Ressource 'consultations'
115			=========================
116
117			Méthode PUT
118			-----------
119
120	fmichon	755	/services/consultations
121	fmichon	753
122
123	fmichon	755
124			====================
125	fmichon	753	Ressource 'messages'
126			====================
127
128			Méthode POST
129			------------
130
131	fmichon	755	/services/messages
132	fmichon	753
133
134	fmichon	755	================================
135	fmichon	753	Ressource 'dossier_autorisation'
136			================================
137
138			Méthode PUT
139			-----------
140
141	fmichon	755	/services/dossier_autorisation
142	fmichon	753
143	fmichon	755
144	fmichon	753	Méthode GET
145			-----------
146
147	fmichon	755	/services/dossier_autorisation
148	fmichon	753