Leitfaden zur Nutzung der FoxPlan-API
Überblick
Die FoxPlan-API ermöglicht es Entwicklern, die Projektmanagement-Funktionen in ihre Anwendungen zu integrieren, um Projektdaten abzurufen und zu verwalten.
Wichtiger Hinweis
„Die Nutzung der FoxPlan-API erfolgt auf eigene Gefahr. Da sämtliche Funktionen über die API verfügbar sind, können Sie Ihre Daten beschädigen, löschen oder korrumpieren." Es wird dringend empfohlen, zuerst in einer nicht produktiven Umgebung zu testen.
Auf die API-Dokumentation zugreifen
Eine vollständige Swagger-Dokumentation ist in FoxPlan unter Einstellungen > Konnektoren > Tab API verfügbar, mit den detaillierten Endpoint-Spezifikationen für authentifizierte Benutzer.
Die Dokumentation setzt eine FoxPlan-Sitzung voraus (die Spezifikation /v3/api-docs ist nicht öffentlich). Der Button Authorize in Swagger nimmt das unten beschriebene id_token an; „Try it out“-Anfragen gehen an den FoxPlan-Server, der die Seite ausgeliefert hat. FoxPlan-interne Funktionen (Cache, Betrieb, Konnektoren) erscheinen nicht in dieser Dokumentation.
Erste Schritte: drei zentrale Etappen
1. Ein API-Konto anlegen
Legen Sie im Tab API ein API-Konto an, indem Sie einen Namen eingeben. Das System liefert eine Auth ID und einen Auth Token, die für die Authentifizierung kombiniert und Base64-kodiert werden müssen.
2. Berechtigungen zuweisen
Geben Sie diesem API-Konto spezifische Rollen (zum Beispiel Workspace Manager), um seine Rechte in der Anwendung festzulegen.
Diese Rolle kostet nichts: Ein API-Konto verbraucht keine Benutzerlizenz, selbst mit der Rolle Arbeitsbereichsadministrator. Es erscheint unter Einstellungen > FoxPlan-Konto > Benutzer und Lizenz mit dem Vermerk „API-Konto" anstelle eines Lizenztyps.
3. Einen Access Token abrufen
Senden Sie eine Anfrage an https://app.fox-plan.com/api/auth mit Basic-Authentifizierung und Ihren Base64-kodierten Zugangsdaten. Die Antwort enthält ein id_token, das für die folgenden Aufrufe zu verwenden ist.
Format der API-Anfragen
Standard-Header:
Authorization: Bearer <id_token>
Beispiel-Endpoint:
GET https://app.fox-plan.com/api/vacations?email=prenom.nom@domaine.com
Klappen Sie in Swagger einen Endpoint auf und klicken Sie auf Try it out, um ihn direkt zu testen:
Derselbe Aufruf kann aus einem Client wie Postman erfolgen, indem der Bearer <id_token> im Header Authorization übergeben wird:
Bewährte Praktiken
- Halten Sie die Richtlinien zur Ratenbegrenzung ein
- Implementieren Sie eine vollständige Fehlerbehandlung
- Bewahren Sie die API-Schlüssel sicher auf — niemals fest im Code hinterlegen
HTTP-Statuscodes
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 400 | Ungültige Anfrage |
| 401 | Nicht authentifiziert |
| 403 | Verboten |
| 404 | Nicht gefunden |
| 500 | Serverfehler |