Accueil > Entrepôt de données publiques > Architecture REST

Architecture REST

Principes généraux

Les API fournies essayent de suivre les principes REST. Les données sont donc constituées de ressources organisées dans des collections, que l’on manipule, en lecture ou en écriture, par des URLs appelées avec les méthodes HTTP.

L’application supporte deux formats : Atom et JSON. Chaque format supporté sera précisé dans les URLs.

Le format Atom est supporté uniquement en lecture, avec la méthode GET. Le format JSON est supporté en lecture (GET) et en écriture (POST et PUT).

Afin d’utiliser l’API, que ce soit en lecture ou en écriture, vous devez posséder un compte réutilisateur, comme expliqué dans l’article qui décrit les données publiques. Ensuite, dès que vous faites une requête, vous devez vous authentifier en HTTP en fournissant votre identifiant et votre mot de passe.

URL de la collection des fiches-visites

Chaque collection a un URL de base par format, auquel on peut adjoindre des paramètres afin de filtrer le contenu.

Liste des fiches au format Atom :

  1. GET http://visites.aquitaine.fr/http.api/atom/fiches

Liste des fiches au format JSON :

  1. GET http://visites.aquitaine.fr/http.api/collectionjson/fiches

URL d’une seule fiche

Chaque ressource a un URL unique par format. L’URL d’une ressource précise est construite en ajoutant l’identifiant après l’URL de la collection. Par exemple ici pour la Gironde :

Fiche de la Gironde au format Atom :

  1. GET http://visites.aquitaine.fr/http.api/atom/fiches/1

Fiche de la Gironde au format JSON :

  1. GET http://visites.aquitaine.fr/http.api/collectionjson/fiches/1

Filtrer la collection des fiches-visites

Il est possible d’ajouter des paramètres à l’URL de la collection des fiches, afin de filtrer les résultats ou de les trier autrement.

Critère type_fiche
Ce critère permet de sélectionner les fiches d’un type particulier : géographique ou patrimoine.

Les valeurs acceptées sont :

  • geo
  • patrimoine

Critère type_geo
Ce critère permet de préciser encore plus le type de fiches que l’on veut lorsqu’on cherche des fiches géographiques, afin de ne sortir que les communes par exemple.

Les valeurs acceptées sont :

  • region
  • departement
  • region_naturelle
  • commune

Il n’est pas besoin d’utiliser type_fiche=geo si on utilise déjà type_geo.

Critères population_min / population_max
Ces critères permettent de filtrer suivant une fourchette de population donnée. Ils peuvent être utilisés ensemble ou séparément (que l’un ou que l’autre).

Implicitement, ce filtrage ne sort alors que des fiches géographiques.

Critères superficie_min / superficie_max
Ces critères permettent de filtrer suivant une fourchette de superficie donnée. Ils peuvent être utilisés ensemble ou séparément (que l’un ou que l’autre).

Implicitement, ce filtrage ne sort alors que des fiches géographiques.

Critère id_parent
Permet de sélectionner les enfants directs d’une fiche donnée. On doit donc lui passer l’identifiant d’une fiche

id_parent=11727 sortira par exemple les deux fiches enfants des Pyrénées-Atlantiques, c’est-à-dire le Pays Basque et le Béarn.

Critère branche
Permet de sélectionner tous les enfants d’une fiche, quelque soit leur niveau d’imbrication.

branche=11727 sortira cette fois-ci toutes les fiches existantes en Pyrénées-Atlantiques (modulo les autres filtres évidemment).

Critère recherche
Ce critère prend une chaîne de caractère d’un ou plusieurs mots afin de lancer une recherche libre dans la base.

recherche=monolithe cherchera les fiches parlant de ce sujet.

Pour un résultat plus pertinent, il est logique d’utiliser conjointement le tri adapté : tri=points.

Tri des résultats

  • par=date (par défaut inverse)
  • par=titre
  • par=points (pertinence de la recherche, par défaut décroissant)
  • sens_fiches=1 pour forcer un ordre croissant
  • sens_fiches=-1 pour forcer un ordre décroissant

Pagination

Par défaut les résultats sortent 100 par 100 en commençant à 0 (donc numérotés de 0 à 99 pour le premier résultat).

Il est possible de changer le pas de la pagination, en utilisant pagination=NN avec un nombre entier.

Ensuite, on peut avancer dans la pagination, en ajoutant le critère debut_fiches avec le résultat à partir duquel on commence. Par exemple debut_fiches=100 pour la deuxième série de 100 résultats (de 100 à 199) avec le pas par défaut.