API

HouseCairn a une API REST, montée sur /api/v1/, avec les mêmes règles que l’interface web : chaque requête ne voit que les logements de son utilisateur (ADR 0004, ADR 0006).

  • JSON pour les requêtes et les réponses, sauf l’envoi d’une photo, en multipart/form-data (POST /api/v1/homes/<home id>/photos/), et l’image et la miniature d’une photo, qui sont servies comme des images.

  • Versionnée : la version 1 ne reçoit que des ajouts ; une rupture ira sur /api/v2/, servie en parallèle de la version 1 pendant une période de dépréciation.

  • Pagination par curseur, jusqu’à 200 éléments par page.

  • Mises à jour avec PATCH ; PUT n’est pas proposé.

  • Authentification par jeton d’API, Authorization: Bearer hc_..., avec les portées read, write et events, liée à un ou plusieurs logements et expirant par défaut après 90 jours (ADR 0007). Il n’existe pas encore d’écran pour créer un jeton.

  • Pièces, éléments et photos d’un logement : /api/v1/homes/<home id>/rooms/, .../items/, .../photos/ et .../search/?q=, avec les mêmes règles que les écrans (ADR 0029, ADR 0030). Un jeton a besoin de la portée read pour les lire et de write pour les modifier, et son utilisateur d’un rôle qui écrit. Les pièces et les éléments se filtrent avec q (nom) ; les éléments avec room ; les photos avec room, item et category.

La référence liste chaque opération. Elle est générée à chaque construction de ce site à partir du schéma OpenAPI 3.1 du code : télécharger le schéma (openapi.json). Une instance en marche sert le même schéma sur /api/schema/ et un explorateur interactif sur /api/docs/, réservés aux personnes connectées.

Modifier cette page sur GitHub Signaler un problème sur cette page