Accueil > Entrepôt de données publiques > API JSON : lecture et écriture

API JSON : lecture et écriture

L’API en JSON utilise la grammaire proposée par Collection+JSON pour décrire la collection, les champs d’une ressource, et les liens entre les collections et ressources.

Contenu d’une collection

Le contenu d’une collection est constitué de trois choses principales :

  • quelques champs qui la décrivent (title, updated, …)
  • une liste de liens de navigation dans l’entrée links
  • la liste des ressources qu’elle contient dans l’entrée items

Tout comme pour l’API Atom, la collection contient certains champs OpenSearch qui décrivent le nombre des résultats et la pagination :

  • totalResults indique le nombre de résultats total par rapport aux filtres (ou pas) fournis dans la requête.
  • startIndex est le numéro de résultat qui commence la liste envoyée, par exemple "0" pour le premier appel, puis la valeur du paramètre debut_fiches lorsqu’il est passé.
  • itemsPerPage contient le pas de pagination qui est "100" par défaut, et peut-être changé avec le paramètre pagination dans la requête.

Des liens de relation "next" et "prev" permettent de naviguer dans la pagination lorsqu’il y en a une.

Contenu d’une fiche

Une fiche est représentée sous forme d’une collection contenant un unique élément dans son tableau items. Elle contient :

  • son URL qui est son identifiant, la date de publication et la date de dernière modification
  • une liste de liens relatifs à cette fiche dans l’entrée links
  • la liste de tous les champs de contenu dans l’entrée data

Les liens possibles sont les suivants :

  • edit pour l’URL d’édition
  • alternate avec comme type "text/html" pour la version HTML de la fiche
  • up pour l’URL JSON et HTML de la fiche parente (il y en a deux)
  • author pour chaque auteur (il peut y en avoir plusieurs)
  • enclosure pour chaque document joint (image ou KML)

Chaque champ contient son nom, sa valeur, mais aussi un titre humainement compréhensible, et donc utilisable dans des interfaces. Ce titre ce trouve dans l’entrée prompt de chaque champ.

Les fiches de type géographique et les fiches de type patrimoine ont certains champs qui leurs sont propres.

Par défaut, tous les champs textuels sont fournis directement en HTML, prêt à être affichés sur le web. Aussi bien sur la collection que sur une fiche, il est possible d’ajouter un paramètre qui permet de fournir les données en texte brut :

  1. GET https://visites.aquitaine.fr/http.api/collectionjson/fiches/1?mode=raw

Certains champs contiennent cependant du balisage léger correspondant à celui reconnu par le logiciel SPIP : reportez-vous à la documentation de SPIP pour en savoir plus.

Proposition d’une nouvelle fiche

Pour proposer une nouvelle fiche, appeler la collection des fiches avec la méthode POST, en lui envoyant la JSON de votre fiche dans le contenu principal de la requête. Ce JSON doit bien évidemment être formaté selon Collection+JSON, mais il n’a besoin que de contenir que l’entrée data contenant les champs.

  1. POST https://visites.aquitaine.fr/http.api/collectionjson/fiches
  1. {
  2. "items" : [
  3. {
  4. "data" : [
  5. {"name":"titre", "value":"Ma nouvelle fiche"},
  6. {"name":"texte", "value":"Une superbe description"}
  7. ]
  8. }
  9. ]
  10. }

Télécharger

Si tout s’est bien passé, vous recevrez une réponse de statut 201, contenant le JSON complet de la nouvelle fiche créé. Et donc avec toutes les informations remplies (liens générés, date, etc). Vous pourrez donc entre autre récupéré son identifiant pour la modifier plus tard.

Modifier une fiche existante

Pour modifier une fiche existante, vous devez appeler l’URL de la fiche avec la méthode PUT, en lui envoyer le JSON des modifications à faire dans le contenu principal de la requête. Là encore votre JSON n’a besoin que de contenu la liste de champs data.

  1. PUT https://visites.aquitaine.fr/http.api/collectionjson/fiches/123456
  1. {
  2. "items" : [
  3. {
  4. "data" : [
  5. {"name":"titre", "value":"Ma nouvelle fiche modifiée"},
  6. {"name":"texte", "value":"Une superbe description\n\nAvec un paragraphe en plus très intéressant."}
  7. ]
  8. }
  9. ]
  10. }

Télécharger

Si tout s’est bien passé, vous recevrez une réponse de statut 200, contenant le JSON complet de la fiche modifiée.

Gestion des erreurs

Si une erreur survient, que ce soit en lecture ou en écriture, l’API JSON renvoie toujours quelque chose, et chaque fois que possible avec un gentil message expliquant l’erreur plus en détail.

Un JSON d’erreur est une collection, mais qui ne contient ni links ni items. À la place, on trouve deux entrées possibles :

  • error est un tableau contenant le statut de l’erreur (le même que le statut HTTP renvoyé, par exemple "404") ainsi qu’un "title" et parfois un "message" plus précis
  • errors, au pluriel, est un tableau de tableaux qui apparait lors des erreurs d’écriture, si vous avez des erreurs dans les champs envoyés : dans ce cas, chaque entrée est une erreur avec un "title" expliquant en détail (par exemple si vous avez oublié le titre errors[titre] contiendra "Ce champ est obligatoire").