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

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	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	fmichon	780	"module": "user",
98			"data": "NA"
99	fmichon	753	}
100
101
102	fmichon	755	Traitement des retours de consultation périmés
103			**********************************************
104
105			/services/maintenance
106
107	fmichon	753	{
108	fmichon	780	"module": "consultation",
109			"data": "NA"
110	fmichon	753	}
111
112
113	fmichon	755	=========================
114	fmichon	753	Ressource 'consultations'
115			=========================
116
117			Méthode PUT
118			-----------
119
120	fmichon	780	Retour d'avis d'une consultation sans fichier
121			*********************************************
122	fmichon	753
123	fmichon	780	/services/consultations/1
124	fmichon	753
125	fmichon	780	{
126			"date_retour": "14/01/2012",
127			"avis": "Favorable"
128			}
129	fmichon	755
130	fmichon	780	Retour d'avis d'une consultation avec fichier
131			*********************************************
132
133			/services/consultations/1
134
135			{
136			"date_retour": "14/01/2012",
137			"avis": "Favorable",
138			"fichier_base64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgM",
139			"nom_fichier": "plop.pdf"
140			}
141
142	fmichon	755	====================
143	fmichon	753	Ressource 'messages'
144			====================
145
146			Méthode POST
147			------------
148
149	fmichon	780	Message 1
150			*********
151
152	fmichon	755	/services/messages
153	fmichon	753
154	fmichon	780	{
155			"type": "Mise à jour de complétude ERP ACC",
156			"date": "16/06/2014",
157			"emetteur": "John Doe",
158			"dossier_instruction": "12345",
159			"contenu":
160			{
161			"Complétude ERP ACC": "non",
162			"Motivation Complétude ERP ACC": "Lorem ipsum dolor sit amet..."
163			}
164			}
165	fmichon	753
166	fmichon	780	Message 2
167			*********
168
169			/services/messages
170
171			{
172			"type": "Mise à jour de complétude ERP SECU",
173			"date": "16/06/2014",
174			"emetteur": "John Doe",
175			"dossier_instruction": "12345",
176			"contenu":
177			{
178			"Complétude ERP SECU": "oui",
179			"Motivation Complétude ERP SECU": "Lorem ipsum dolor sit amet..."
180			}
181			}
182
183			Message 3
184			*********
185
186			/services/messages
187
188			{
189			"type": "Mise à jour de qualification",
190			"date": "16/06/2014",
191			"emetteur": "John Doe",
192			"dossier_instruction": "12345",
193			"contenu":
194			{
195			"Confirmation ERP": "oui",
196			"Type de dossier ERP": "Lorem ipsum dolor sit amet...",
197			"Catégorie de dossier ERP": "Lorem ipsum dolor sit amet..."
198			}
199			}
200
201			Message 4
202			*********
203
204			/services/messages
205
206			{
207			"type": "Dossier à enjeux ERP",
208			"date": "16/06/2014",
209			"emetteur": "John Doe",
210			"dossier_instruction": "12345",
211			"contenu":
212			{
213			"Dossier à enjeux ERP" : "oui"
214			}
215			}
216
217	fmichon	755	================================
218	fmichon	753	Ressource 'dossier_autorisation'
219			================================
220
221			Méthode PUT
222			-----------
223
224	fmichon	755	/services/dossier_autorisation
225	fmichon	753
226	fmichon	755
227	fmichon	753	Méthode GET
228			-----------
229
230	fmichon	755	/services/dossier_autorisation
231	fmichon	753