API HTTP REST pour GIS
Avertissement : Ce serveur HTTP REST est un démonstrateur et un outil de développement lié au projet OAuthSD. Il peut être indisponible et les données enregistrées effacées à tout moment.
Radar propose une API REST qui permet d’automatiser l’interrogation et la mise à jour de la base de données géographique. Les objets sont représentés au format JSON.
L’accès aux données est sécurisé par OAuth Server by DnC auquel est délégué le contrôle de chaque accès à l’API. Il en résulte notamment que les requêtes ne peuvent être simplement passées par un navigateur ou en ligne de commande, seule une application cliente configurée sur ce serveur peut accéder aux données.
Collections
Les collections représentent sous le format JSON les objets que Radar met à disposition par le moyen de l’API REST. Il s’agit des collections suivantes :
gis
Lister un spot
GET https://r.dnc.global/http.api/collectionjson/gis/NNRetourne le spot ayant pour id_gis NN.
Exemple d’appel côté client en jQuery :
<div id="result"></div>
<script>
$.ajax({
url: 'https://r.dnc.global/http.api/collectionjson/gis/27',
dataType: 'json',
type: 'GET',
contentType: 'application/json',
data: 'token=#SESSION{oauth_token}',
timeout: 15000,
success: function(data) {
var text = '<b>Requete : ' + data.collection.href + '</b><br /><br />';
items = data.collection.items;
for (var i=0; i < items.length; i++ ) {
for (var j=0; j < items[i].data.length; j++ ) {
text += items[i].data[j].name + '=' + items[i].data[j].value + "<br />";
}
text += "<br />";
}
$("#result").html(text);
},
error: function(oops) {
var code='<script>window.open("http://oa.dnc.global/oauth/authorize.php?response_type=code&client_id=radar&state=xyz","nom_de_ma_popup","menubar=no, scrollbars=no, top=100, left=100, width=600, height=600");<\/script>';
$("#result").html(code);
}
});
</script>Lister les spots à proximité, avec indication de la distance
GET http://r.dnc.global/http.api/collectionjson/gis?lat=DD.ddd&lon=DD.ddd[&limit=NN][&dmax=DD]Liste les spots à proximité du point de coordonnées lat,lon, avec indication
de la distance en km, par distance croissante.
Le paramètre limit permet de limiter le nombre de spots listés.
Si le paramètre limit n’est pas précisé, le nombre de points est limité à 100.
Le paramètre dmax permet de limiter la liste aux spots situés à une distance
inférieure à la valeur indiquée en km.
Exemple d’appel côté client en jQuery :
<div id="result"></div>
<script>
$(function () {
$.ajax({
url: 'https://r.dnc.global/http.api/collectionjson/gis',
dataType: 'json',
type: 'GET',
contentType: 'application/json',
data: 'lat=47.8655638&lon=5.3314162&dmax=10&token=#SESSION{oauth_token}',
timeout: 15000,
success: function(data) {
var text = '<b>Requete : ' + data.collection.href + '</b><br /><br />';
items = data.collection.items;
for (var i=0; i < items.length; i++ ) {
for (var j=0; j < items[i].data.length; j++ ) {
text += items[i].data[j].name + '=' + items[i].data[j].value + "<br />";
}
text += "<br />";
}
$("#result").html(text);
},
error: function(oops) {
// oops.statusText returns error
var code='<script>window.open("http://oa.dnc.global/oauth/authorize.php?response_type=code&client_id=radar&state=xyz","nom_de_ma_popup","menubar=no, scrollbars=no, top=100, left=100, width=600, height=600");<\/script>';
$("#result").html(code);
//}
}
});
});
</script>Lors de la demande de vos login et mot de passe, si vous ne voulez pas vous inscrire, vous pourrez utiliser les identifiants suivants :
E-mail or pseudo : bebert
Password : 012345678
Notes :
Remarquez le jeton d’accès (access token) dans l’URL, dont la valeur est tirée de la session de l’application cliente au moyen d’ une balise SPIP. L’application cliente a obtenu ce jeton comme décrit ici : Obtenir un jeton d’accès.
On utilise items[i].data, qui est un array, pour énumérer les champs de la réponse. On peut également utiliser objects[i] qui regroupe les champs dans un objet, ce qui permet par exemple d’écrire objects[i].titre.
Remarquez l’appel à la fonction d’autorisation de OAuth Server by DnC effectué dans une fenêtre popup.
Avertissement : Les exemples précédents montrent un appel à l’API effectué depuis le user agent ; ceci dévoile le jeton d’accès, ce qui n’est pas une bonne pratique. Pour la sécurité des données, on préfèrera effectuer les appels côté serveur, quitte à utiliser ajax pour afficher le résultat de la requête.
Sécurité
La sécurité de l’API REST Radar repose sur les deux dispositifs suivants :
Authentification
Vous devez commencer toute session de l’API par une demande d’authentification.
L’authentification est déléguée à OAuth Server By DnC. L’utilisateur final doit s’inscrire sur ce serveur et s’identifier sur ce même serveur au début de chaque session.
Un administrateur (au sens de SPIP) pourra accéder à l’API sans s’identifier avec OAuth.
Inscription de l’application cliente
Il est nécessaire d’inscrire l’application cliente, origine des requêtes, sur OAuth Server by DnC. Dans l’état actuel du développement, l’inscription ne peut être finalisée en ligne ; elle sera faite sur demande auprès de DnC.
Informations pour les développeurs
Architecture
Cet API est fondé sur :
Le plugin SPIP API Collection+JSON
Le plugin SPIP Serveur HTTP abstrait
API Collection+JSON.
Intégration de l’API dans une application avec OAuthSD
Du côté de l’API :
Le plugin collectionjson_gis développé par DnC étend la portée du plugin Collection+JSON aux objets GIS et assure l’interface avec OAuth Server by DnC. Ce plugin suffit à transformer une application SPIP en serveur de données REST sécurisé.
La seule modification porte sur les fonctions d’autorisation :
SPIP
<?php
// Sécurité
if (!defined('_ECRIRE_INC_VERSION')) {
return;
}
// Important : écraser les autorisations du plugin http abstrait :
/* Voir un objet par HTTP : on redirige vers la fonction pour voir l'objet
function autoriser_get_ressource($faire, $quoi, $id, $qui, $options){
return autoriser('voir', $quoi, $id, $qui, $options);
} //*/
function autoriser_get_ressource($faire, $quoi, $id, $qui, $options){
}
// Voir l'index, contenant à priori les collections disponibles
function autoriser_get_index($faire, $quoi, $id, $qui, $options){
}
// Voir une liste d'objet par HTTP
function autoriser_get_collection($faire, $quoi, $id, $qui, $options){
}
// Ajouter un objet par HTTP
function autoriser_post_collection($faire, $quoi, $id, $qui, $options){
}
// Modifier un objet par HTTP
function autoriser_put_ressource($faire, $quoi, $id, $qui, $options){
}
// Supprimer un objet par HTTP
function autoriser_delete_ressource($faire, $quoi, $id, $qui, $options){
}
// Ecraser aussi l'appel du pipeline
function collectionjson_gis_autoriser() {
}
/*
Attention aux deux autorisations définies par collectionjson_autorisations.php !
Il n'y a que cela en plus :
*/
function autoriser_gis_get_ressource($faire, $quoi, $id, $qui, $options) {
return _autoriser_gis($faire, $quoi, $id, $qui, $options);
}
function autoriser_gis_get_collection($faire, $quoi, $id, $qui, $options) {
return _autoriser_gis($faire, $quoi, $id, $qui, $options);
}
function _autoriser_gis($faire, $quoi, $id, $qui, $options) {
if ( $qui['statut'] == '0minirezo' ) {
// Toujours autoriser un administrateur
return true;
} else if ( $accesstoken = $_GET['token'] ) {
// Vérifier le jeton d'accès
return oauth_authorize($accesstoken);
} else return false;
}
/*
Autorisation avec OAuth Server by DnC
Auteur : Bertrand degoy
Copyright (c) 2016 DnC
*/
function oauth_authorize($token) {
$sanitized_token = preg_replace('/[^a-f0-9"\']/', '', $token);
if ( !empty($sanitized_token) AND $sanitized_token === $token ) {
// Interroger OAuth Server by DnC
include_spip('inc/distant');
// Vérifier le jeton d'accès (access token)
$url = "http://oa.dnc.global/oauth/resource.php?access_token=" . $token;
$res = recuperer_url_cache( $url, array('delai_cache' => 300) );
if ( (int)$res['status'] === 200 ) {
if ( isset($_SERVER["HTTP_ORIGIN"]) ) {
// Accès HTTP (CORS) : autoriser l'origine
$issuer = trim(strtr($_SERVER["HTTP_ORIGIN"], '<>"\'', '[]##'));
header('Access-Control-Allow-Origin', $issuer);
}
return true ;
}
}
return false;
}
?>Du côté de l’application cliente :
Voyez le site OAuthSD : Une fonction pour tout simplifier
RSS 2.0