Aller au contenu principal

API v1

Les ressources v1 pendent directement du client : client.projects, client.workItems, client.cycles, et ainsi de suite. Chaque appel limité à un espace de travail prend d'abord le slug de l'espace de travail, puis l'id du projet là où l'URL en a un. Contrairement à la v2, project ici est l'UUID du projet, et les classes plus anciennes épellent la méthode de suppression delete ou del (suivez la liste de méthodes que votre éditeur affiche).

import { PlaneClient } from "@hoyasumii/plane";

const client = new PlaneClient({ apiKey: "your-api-key" });

const projects = await client.projects.list("workspace-slug");

const project = await client.projects.create("workspace-slug", {
  name: "My Project",
  description: "A new project",
});

const item = await client.workItems.create("workspace-slug", project.id, { name: "First task" });
await client.workItems.comments.create("workspace-slug", project.id, item.id, { comment_html: "<p>Hello</p>" });

// Un élément de travail par sa clé humaine, à l'échelle de l'espace de travail.
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

Ressources​

  • Projects : gestion et organisation des projets
  • WorkItems : gestion des éléments de travail avec des opérations CRUD complètes
  • WorkItemTypes : définitions et gestion de types d'élément de travail personnalisés
  • WorkItemProperties : propriétés personnalisées pour les éléments de travail
  • Labels : catégorisation et étiquetage
  • States : gestion des états de workflow
  • Users : gestion des utilisateurs et des profils
  • Roles : définitions des rôles d'espace de travail et de projet (lecture seule)
  • Estimates : estimations de projet et points d'estimation
  • Modules : organisation des fonctionnalités et gestion des modules
  • Cycles : gestion des sprints et des itérations
  • Customers : gestion et opérations sur les clients
  • Pages : gestion des pages d'espace de travail et de projet
  • Links : liaison et relations des éléments de travail
  • Workspace : opérations au niveau de l'espace de travail
  • Epics : gestion et organisation des épopées
  • Intake : gestion des formulaires et demandes d'admission
  • Stickies : gestion des pense-bêtes
  • Teamspaces : gestion des espaces d'équipe
  • Milestones : suivi et gestion des jalons
  • Initiatives : gestion des initiatives
  • WorkspaceTemplates : modèles d'élément de travail, de projet et de page au niveau de l'espace de travail
  • WorkspaceWorkItemTypes : gestion des types d'élément de travail au niveau de l'espace de travail, avec liens de propriétés
  • WorkspaceWorkItemProperties : gestion des propriétés personnalisées au niveau de l'espace de travail, avec options
  • WorkspaceProjectLabels : gestion des labels de projet au niveau de l'espace de travail
  • WorkspaceProjectStates : gestion des états de projet au niveau de l'espace de travail
  • WorkItemRelationDefinitions : définitions de types de relation personnalisés entre éléments de travail
  • Releases : gestion des releases avec tags, labels, labels d'élément, changelog, commentaires, liens et éléments de travail
  • Collections : dossiers qui regroupent les pages d'espace de travail, avec gestion des membres et des pages
  • AgentRuns : orchestration des exécutions d'agent IA et suivi de leur activité
  • Workflows : gestion du workflow de projet avec attachements d'état, transitions, hooks de transition, activités et approbations d'élément de travail
  • ProjectTemplates : gestion des modèles d'élément de travail et de page par projet
  • Features : gestion des fonctionnalités d'espace de travail et de projet
  • WorkspaceStates : états d'élément de travail au niveau de l'espace de travail (catalogue), sous gouvernance d'espace de travail — lectures à double mode, écritures réservées à la gouvernance
  • WorkspaceWorkflows : catalogue de workflows au niveau de l'espace de travail, sous gouvernance d'espace de travail, avec chaîne (états), transitions, usage, activités et hooks de transition
  • WorkItemTypeGovernance : régit les workflows qu'un type d'élément de travail au niveau de l'espace de travail peut utiliser (modes any/constrained/required), avec des épingles par projet et les points de terminaison de sélection/aperçu de repli côté projet
  • Instance : configuration et métadonnées de l'instance (version, édition, fournisseurs d'authentification, SMTP, limites de téléchargement) depuis GET /api/instances/

Les sous-ressources pendent de leur parent : workItems.comments, workItems.attachments, workItems.activities, workItems.relations, workItems.workLogs, customers.properties, customers.requests, teamspaces.members, teamspaces.projects, initiatives.labels, initiatives.projects, initiatives.epics, agentRuns.activities, workItemProperties.options, workItemProperties.values, et ainsi de suite.

Informations sur l'instance​

const info = await client.instance.retrieve();
console.log(info.instance.current_version, info.config.is_smtp_configured);

Télécharger des pièces jointes​

workItems.attachments.download résout l'URL signée d'une pièce jointe et la télécharge, sans envoyer la clé d'API à l'hébergeur de stockage. Avec maxBytes, un fichier plus grand est refusé avec AttachmentTooLargeError : dès le départ quand le stockage annonce son Content-Length, sinon dès que le corps dépasse le plafond.

import { AttachmentTooLargeError } from "@hoyasumii/plane";

try {
  const { data, contentType } = await client.workItems.attachments.download("acme", projectId, itemId, "asset-1", {
    maxBytes: 20 * 1024 * 1024,
  });
  console.log(contentType, data.length);
} catch (error) {
  if (error instanceof AttachmentTooLargeError) console.log("too large");
  else throw error;
}

Erreurs​

Une requête v1 échouée lève HttpError, avec le code de statut, le corps de la réponse et les en-têtes de la réponse (en minuscules, donc headers["retry-after"] sur un 429). Voir Erreurs pour toute la hiérarchie.