Proposer une modification par l’API

Depuis un script ou une tâche de CI, prévisualisez une modification sans rien enregistrer, puis soumettez-la comme proposition qu’une personne applique.

Une tâche qui dérive un schéma de votre code, ou qui le garde aligné sur un dépôt, ne devrait pas écraser le schéma. Elle prévisualise la modification, puis la soumet comme proposition. La proposition attend dans iyedy qu’une personne qui peut modifier le schéma l’applique ou la refuse.

Avant de commencer

• Un jeton avec cartouche.read et cartouche.propose : un jeton d’accès personnel, ou un compte de service pour la CI.
• Au moins le rôle de contributeur dans l’espace de travail du schéma. Avec le rôle de lecteur, les routes ci-dessous n’enregistrent rien.
• Les identifiants de l’organisation, de l’espace de travail et du schéma : voir Votre premier appel à l’API. Dans le texte ci-dessous, W désigne /v1/t/{tenantId}/w/{workspaceId}.

Proposer une modification

1. Lire le schéma et sa version

   GET /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/source HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   

   La réponse donne le did du schéma, son name, sa classification, sa version actuelle et sa définition entière dans text. Gardez la version : c’est la base de votre modification.

2. Préparer la définition entière

   Votre tâche modifie la définition et la garde entière. Une proposition remplace tout le schéma : ce qu’elle omet est supprimé.

3. Prévisualiser la modification

   POST /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/preview HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   Content-Type: application/json
   

   Champ	Obligatoire	Valeur
   text	oui	la définition proposée entière
   baseVersion	non	la version lue à l’étape 1 ; si le schéma a avancé depuis, la réponse est 409 conflict

   Rien n’est enregistré. La réponse dit si la modification est valide (valid), avec ses diagnostics (ligne et message), les différences ligne par ligne dans patch, les comptes et la liste des éléments ajoutés, retirés et modifiés dans changes, et dans findings les constats avant et après, avec ceux que la modification introduit et résout. Corrigez ce que signalent les diagnostics et prévisualisez à nouveau jusqu’à ce qu’elle soit valide.

4. Soumettre la proposition

   POST /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/proposals HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   Content-Type: application/json
   

   Champ	Obligatoire	Valeur
   text	oui	la définition proposée entière, telle que prévisualisée
   baseVersion	non	la version dont part la modification
   rationale	non	pourquoi cette modification, en une ou deux phrases, pour la personne qui relit

   iyedy prévisualise à nouveau la modification et l’enregistre : la réponse est 201 avec la proposition (proposal) et sa prévisualisation (preview). Une modification invalide, ou qui ne change rien, répond 422 validation_failed et rien n’est enregistré.

   Dans iyedy, le panneau Assistant du schéma liste votre modification sous Propositions à examiner, avec votre nom ou celui du compte de service.
5. La suivre

   GET /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/proposals?status=open&mine=1 HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   

   Chaque proposition a son statut (ouverte, acceptée, refusée, retirée) et signale si le schéma a bougé depuis sa création. Pour retirer une de vos propositions ouvertes, appelez POST W/diagrams/{did}/proposals/{pid}/withdraw.

Limites

• Une personne décide. Aucun jeton ne peut accepter ou refuser une proposition : cela se fait dans l’app. Voir Comment les propositions arrivent à votre équipe.
• 30 jours. Une proposition que personne ne traite expire et est supprimée au bout de 30 jours.
• Les propositions ouvertes sont plafonnées : 50 par schéma et 10 par auteur. Au-delà, 429 rate_limited ; traitez ou retirez-en d’abord.
• Enregistré sans le contenu. Dans une organisation, chaque proposition est enregistrée dans le journal d’audit par identifiants et comptes, jamais avec la définition proposée.

Si cela ne fonctionne pas

Tous les codes : Limites de débit et erreurs.