Contrat HTTP versionné

Une interface stable entre vos outils et DemioFlow

Le contrat v1 décrit l’authentification, les ressources, les erreurs et les garanties que les clients peuvent utiliser sans dépendre du schéma Firestore.

Principes du contrat

La façade publique utilisée par le CLI est https://app.demioflow.com/v1.
Le serveur déduit le propriétaire depuis le jeton ; aucun client ne fournit de userId.
Les options et champs inconnus sont rejetés avec UNKNOWN_OPTION pour détecter les fautes de frappe.
Les dates et instants utilisent ISO 8601 ; les instants sont renvoyés en UTC.

Authentification navigateur

Le CLI initialise un code d’appareil, ouvre la page d’autorisation, puis échange l’approbation contre une session Firebase. Le mot de passe reste exclusivement dans l’application web.

POST /v1/auth/device/code
POST /v1/auth/device/approve
POST /v1/auth/device/token

Les codes expirent, sont à usage unique et la réponse de jeton ne doit jamais être enregistrée dans les logs.

Ressources et actions

Ressource	Collection v1
Areas	/v1/areas
Projects	/v1/projects
Sections	/v1/projects/{projectId}/sections
Tasks	/v1/tasks
Goals	/v1/goals
Habits	/v1/habits
Tags	/v1/tags

Les relations sont validées côté serveur. Une section doit appartenir au même projet que la tâche qui la référence.

POST /v1/projects/{projectId}/sections:reorder
POST /v1/projects/reorder
POST /v1/tasks/reorder
POST /v1/tags/reorder
POST /v1/sections/{sectionId}:move
POST /v1/tags/{tagId}:link

Erreurs prévisibles

{
  "error": {
    "code": "PROJECT_MISMATCH",
    "message": "The section must belong to the selected project.",
    "retryable": false
  },
  "meta": { "requestId": "req_…", "apiVersion": "1.0" }
}

HTTP	Codes courants	Sens
400	UNKNOWN_OPTION / METHOD_NOT_ALLOWED	Option ou méthode inconnue
401	AUTH_REQUIRED / AUTH_INVALID	Jeton absent ou invalide
404	NOT_FOUND / ROUTE_NOT_FOUND	Ressource ou route introuvable
422	INVALID_* / *_MISMATCH	Valeur, relation ou état invalide
500	INTERNAL_ERROR	Erreur serveur inattendue
503	API_UNAVAILABLE	Façade temporairement indisponible

Automatisation sûre

Le champ retryable indique si l’appel peut être retenté. Aujourd’hui, le CLI traduit les erreurs réseau et serveur en codes de sortie non nuls ; une clé d’idempotence et les préconditions If-Match font partie de la feuille de route du contrat, pas des garanties de l’API déployée.

Source normative

La spécification OpenAPI versionnée du dépôt de l’application reste la source machine-readable. Cette page est le guide humain et évolue avec chaque extension publique du contrat.