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é ::

Pour n'avoir pas du besoin d'ecrire "rest_entry.php" dans l'URL appelle depuis ERP, utilisez les
trois lignes dessous:

        RewriteEngine On
        RewriteCond %{REQUEST_URI} ^.*/<path_to>/services/(.*[^/])
        RewriteRule ^(.*)/services/(.*)$ /<path_to>/services/rest_entry.php/$2 [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
-----------

Retour d'avis d'une consultation sans fichier
*********************************************

/services/consultations/1

{
"date_retour": "14/01/2012",
"avis": "Favorable"
}

Retour d'avis d'une consultation avec fichier
*********************************************

/services/consultations/1

{
"date_retour": "14/01/2012",
"avis": "Favorable",
"fichier_base64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgM",
"nom_fichier": "plop.pdf"
}

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

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

Message 1
*********

/services/messages

{
"type": "Mise à jour de complétude ERP ACC",
"date": "16/06/2014", 
"emetteur": "John Doe",
"dossier_instruction": "12345", 
"contenu":
{
"Complétude ERP ACC": "non",
"Motivation Complétude ERP ACC": "Lorem ipsum dolor sit amet..."
}
}

Message 2
*********

/services/messages

{
"type": "Mise à jour de complétude ERP SECU",
"date": "16/06/2014", 
"emetteur": "John Doe",
"dossier_instruction": "12345", 
"contenu":
{
"Complétude ERP SECU": "oui",
"Motivation Complétude ERP SECU": "Lorem ipsum dolor sit amet..."
}
}

Message 3
*********

/services/messages

{
"type": "Mise à jour de qualification",
"date": "16/06/2014", 
"emetteur": "John Doe",
"dossier_instruction": "12345", 
"contenu":
{
"Confirmation ERP": "oui",
"Type de dossier ERP": "Lorem ipsum dolor sit amet...",
"Catégorie de dossier ERP": "Lorem ipsum dolor sit amet..."
}
}

Message 4
*********

/services/messages

{
"type": "Dossier à enjeux ERP",
"date": "16/06/2014", 
"emetteur": "John Doe",
"dossier_instruction": "12345", 
"contenu":
{
"Dossier à enjeux ERP" : "oui"
}
}

================================
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	797	Pour n'avoir pas du besoin d'ecrire "rest_entry.php" dans l'URL appelle depuis ERP, utilisez les
39			trois lignes dessous:
40	mlimic	515
41	mlimic	797	RewriteEngine On
42			RewriteCond %{REQUEST_URI} ^./<path_to>/services/(.[^/])
43			RewriteRule ^(.)/services/(.)$ /<path_to>/services/rest_entry.php/$2 [QSA,L]
44
45	fmichon	753	Dans la configuration de votre virtualhost penser à ce que les méthodes HTTP
46			nécessaires GET, PUT, POST, DELETE soient autorisées.
47	mlimic	515
48	fmichon	753	Redémarrer Apache
49	fmichon	755	-----------------
50	mlimic	515
51	fmichon	753	Pour que les changements prennent effet il faut redémarrer le serveur Apache ::
52	mlimic	515
53	fmichon	753	$ /etc/init.d/apache2 restart
54	mlimic	515
55
56	fmichon	755	============================================================
57	fmichon	753	Utilisation des services REST avec curl en ligne de commande
58	fmichon	755	============================================================
59	fmichon	753
60	mlimic	522	Pour envoyer une demande concernant les utilisateurs, avec curl et simple HTTP authetification, on fait :
61	mlimic	515
62	mlimic	522	- en cas de GET :
63			$ curl --user <username> -v http://<server>/<path_to>/services/utilisateurs/<ID>
64	mlimic	515
65	mlimic	522	Le '<ID>' doit etre remplace par l'ID d'un utilisateur, le '<server>' doit etre remplace par un server IP
66			ou un domain name, et '<path_to>' est le chemin, dans la hierarchie des fichiers, ou se trouve openfoncier.
67	mlimic	515
68	mlimic	522	- en cas de POST :
69			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
70	mlimic	515
71	mlimic	522	- en cas de PUT:
72			$ curl --user <username> -v -H "Content-Type: application/json" -d '{"nom":"Changed_name"}' -X PUT http://<server>/<path_to>/services/utilisateurs/<ID>
73	mlimic	515
74	mlimic	522	- en cas de DELETE:
75			$ curl --user <username> -v -X DELETE http://localhost/~mirna/head_openfoncier/services/utilisateurs/<ID>
76	mlimic	515
77	mlimic	522	En cas d'encryptage SSL des donnes, curl doit etre utilise avec l'option E comme par exemple :
78			$ 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>
79	mlimic	515
80	mlimic	522	Le key_certificate.concat contient la cle avec le certificat colle a la fin de la cle.
81	fmichon	753
82
83			*****************************************
84			Description des services REST openFoncier
85			*****************************************
86
87	fmichon	755	=======================
88	fmichon	753	Ressource 'maintenance'
89			=======================
90
91			Méthode POST
92			------------
93
94	fmichon	755	Synchronisation des utilisateurs via LDAP
95			*****************************************
96
97	fmichon	753	/services/maintenance
98
99			{
100	fmichon	780	"module": "user",
101			"data": "NA"
102	fmichon	753	}
103
104
105	fmichon	755	Traitement des retours de consultation périmés
106			**********************************************
107
108			/services/maintenance
109
110	fmichon	753	{
111	fmichon	780	"module": "consultation",
112			"data": "NA"
113	fmichon	753	}
114
115
116	fmichon	755	=========================
117	fmichon	753	Ressource 'consultations'
118			=========================
119
120			Méthode PUT
121			-----------
122
123	fmichon	780	Retour d'avis d'une consultation sans fichier
124			*********************************************
125	fmichon	753
126	fmichon	780	/services/consultations/1
127	fmichon	753
128	fmichon	780	{
129			"date_retour": "14/01/2012",
130			"avis": "Favorable"
131			}
132	fmichon	755
133	fmichon	780	Retour d'avis d'une consultation avec fichier
134			*********************************************
135
136			/services/consultations/1
137
138			{
139			"date_retour": "14/01/2012",
140			"avis": "Favorable",
141			"fichier_base64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgM",
142			"nom_fichier": "plop.pdf"
143			}
144
145	fmichon	755	====================
146	fmichon	753	Ressource 'messages'
147			====================
148
149			Méthode POST
150			------------
151
152	fmichon	780	Message 1
153			*********
154
155	fmichon	755	/services/messages
156	fmichon	753
157	fmichon	780	{
158			"type": "Mise à jour de complétude ERP ACC",
159			"date": "16/06/2014",
160			"emetteur": "John Doe",
161			"dossier_instruction": "12345",
162			"contenu":
163			{
164			"Complétude ERP ACC": "non",
165			"Motivation Complétude ERP ACC": "Lorem ipsum dolor sit amet..."
166			}
167			}
168	fmichon	753
169	fmichon	780	Message 2
170			*********
171
172			/services/messages
173
174			{
175			"type": "Mise à jour de complétude ERP SECU",
176			"date": "16/06/2014",
177			"emetteur": "John Doe",
178			"dossier_instruction": "12345",
179			"contenu":
180			{
181			"Complétude ERP SECU": "oui",
182			"Motivation Complétude ERP SECU": "Lorem ipsum dolor sit amet..."
183			}
184			}
185
186			Message 3
187			*********
188
189			/services/messages
190
191			{
192			"type": "Mise à jour de qualification",
193			"date": "16/06/2014",
194			"emetteur": "John Doe",
195			"dossier_instruction": "12345",
196			"contenu":
197			{
198			"Confirmation ERP": "oui",
199			"Type de dossier ERP": "Lorem ipsum dolor sit amet...",
200			"Catégorie de dossier ERP": "Lorem ipsum dolor sit amet..."
201			}
202			}
203
204			Message 4
205			*********
206
207			/services/messages
208
209			{
210			"type": "Dossier à enjeux ERP",
211			"date": "16/06/2014",
212			"emetteur": "John Doe",
213			"dossier_instruction": "12345",
214			"contenu":
215			{
216			"Dossier à enjeux ERP" : "oui"
217			}
218			}
219
220	fmichon	755	================================
221	fmichon	753	Ressource 'dossier_autorisation'
222			================================
223
224			Méthode PUT
225			-----------
226
227	fmichon	755	/services/dossier_autorisation
228	fmichon	753
229	fmichon	755
230	fmichon	753	Méthode GET
231			-----------
232
233	fmichon	755	/services/dossier_autorisation
234	fmichon	753