Yoplanning API-Dokumentation

Einführung

Die Yoplanning API ist nach dem REST-Prinzip aufgebaut. Unsere API stellt vorhersehbare ressourcenorientierte URLs bereit und verwendet HTTP-Antwortcodes, um Fehler und Erfolg von API-Aufrufen anzuzeigen. Wir nutzen integrierte HTTP-Funktionen wie HTTP-Authentifizierung und HTTP-Verben, die von Standard-HTTP-Clients verstanden werden. Alle Methoden in unserer API geben JSON zurück.

Authentifizierung

Um zu beginnen, müssen Sie ein API-Token anfordern, um die Yoplanning-API abfragen zu können. Bitte kontaktieren Sie uns hierzu. Sobald Sie Ihren Token in der Hand haben, können Sie mit der Arbeit mit der API beginnen. Alle API-Methoden erfordern eine Authentifizierung.

Wir verwenden ein standardmäßiges tokenbasiertes Authentifizierungssystem. Geben Sie zur Authentifizierung einfach Ihr API-Token im Header jeder Anfrage wie folgt an: „Autorisierung: Token 4804c2cb4d87a13146d4de029f407c82149f2ada“. Achtung: Das Leerzeichen zwischen „Token“ und dem Token ist wichtig.

Hier ist ein vollständiges Beispiel für die Verwendung von Curl:

curl -H "Content-Type: application/json" https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead -H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'

Wenn Sie kein Token angeben oder das Token ungültig ist, antwortet die API mit einem HTTP 401-Code (nicht autorisiert) und stellt Ihnen im Antwort-JSON ein Feld „Details“ zur Verfügung, damit Sie das Problem besser verstehen können.

Berechtigungen

Als Sie Ihr API-Token angefordert haben, wurden Ihnen bestimmte Berechtigungen für eine bestimmte Gruppe von Teams erteilt. Das bedeutet, dass Sie wahrscheinlich nicht jede Methode in der API verwenden können. Wenn Sie die Yoplanning-API ohne Berechtigungen aufrufen, antwortet die API mit dem HTTP-Code 403 (Verboten).

Abfragen einschränken

Aus Sicherheitsgründen ist die Anzahl der Anfragen, die Sie stellen können, begrenzt. Sie können bis zu 5 Anfragen pro Sekunde und 1000 Anfragen pro Tag senden. Bei Überschreitung dieser Rate antwortet der Server mit dem HTTP-Code 429 (Zu viele Anfragen).

Überblick

Team

Das Team ist das grundlegendste Konzept in Yoplanning (einem kollaborativen Tool). Fast alle Methoden akzeptieren einen teamId-Parameter in der URL, was bedeutet, dass alle Aktionen relativ zu einem Team sind.

UUID

Viele Methoden erfordern einen „pk“-Parameter in der URL. Dies ist die eindeutige Kennung für die Ressource, die Sie abrufen/erstellen/aktualisieren/löschen möchten. Yoplanning verwendet UUID (Version 4) als eindeutige Kennung für alle Ressourcen.

HTTP-Endpunkte und Verben

Für viele Ressourcen stehen zwei Endpunkte zur Verfügung:

• Eine, um auf eine bestimmte Instanz zuzugreifen. Die URL endet normalerweise mit „“.

• Einer für den Zugriff auf den Instanzmanager: Diese Endpunkte verwenden die folgenden HTTP-Verben:

  • GET: Liste aller Ressourcen abrufen (siehe Paginierung)

  • POST: Erstellen Sie eine neue Ressource (die Kennung wird vom Server generiert)

Paging

Für alle API-Methoden, die eine große Liste von Ressourcen bereitstellen, wird Paging verwendet. Dies bedeutet, dass nicht alle Ergebnisse in einer einzigen Abfrage angegeben werden. Sie müssen mehrere Abfragen durchführen, um die vollständige Liste der Ressourcen zu erhalten.

Filter

Für einige Endpunkte können Sie Ergebnisse filtern, indem Sie der Anfrage Abfrageparameter hinzufügen.

Erweiterbare Felder

Bei einigen Endpunkten enthält das Ressourcenobjekt verschachtelte Ressourcen. Um das Senden weiterer Anfragen zu vermeiden, können Sie den Erweiterungsmechanismus verwenden