CentralPlanner API Dokumentation

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Kontakte Reservierungen

Sonstiges: Schlagwörter

Die CentralPlanner API ist zustandsbehaftet nach dem REST Model. Die Kommunikation findet ausschließlich verschlüsselt über das HTTPs Protokoll statt, wobei die gewünschte Operation über das HTTP Verb bestimmt wird. Die eigentlichen Daten werden im JSON Format übertragen.
Bei Fragen melde dich kurz per E-Mail an developer [at] 42he.com.

Hinweis: Die Beispiele verwenden das Unix Tool curl, welches sich sehr gut zum Testen eignet. Natürlich kannst du jede beliebige HTTP Bibliothek in der Programmiersprache deiner Wahl nutzen.

Grundlagen für die Nutzung der API

Die gewünschte Aktion wird über den Aufruf der jeweiligen Ressource mit dem gewünschten Verb (GET, PUT, POST oder DELETE) ausgeführt. Parameter wie beispielsweise der Account werden über die HTTP URI übergeben. Diese ist nach einem festen Schema aufgebaut:

https://centralplanner.net/api/:objects/:id/:action.json

Jedes Objekt lässt sich eindeutig über seine URI identifizieren. Diese ist persistent und ändert sich bis zum Löschen des Elementes nicht mehr. Hierbei ist zu beachten, das die IDs nicht sequentiell sind. Eine Objekt kann z.B. die ID 5 haben, das nächste die ID 324. Um eine Liste aller Kontakte in einem CentralPlanner Account zu erhalten, kann man eine GET Anfrage wie folgt senden. Als Rückgabe erhält man ein Dokument im JSON Format.

curl "https://centralplanner.net/api/contacts" -H 'Authorization: Token token="my-api-token"'

Zudem gibt es für verschachtelte Objekte (1-n Relationen) verschachtelte Routen. Um also zum Beispiel für den Kontakt mit der ID 4759 alle Schlagwörter (tags) oder Reservierungen (bookings) zu erhalten ist folgender Aufruf nötig:

curl "https://centralplanner.net/api/contacts/4759/tags" -H 'Authorization: Token token="my-api-token"'

Die verschachtelten Routen sind allgemein nach dem folgenden Schema aufgebaut:

https://centralplanner.net/api/:objects/:id/:subobject:/:id/:action.json

Paginierung

Die INDEX Funktionen sind grundsätzlich paginiert, d.h. die API liefert nicht alle Ergebnisse auf einmal zurück, sondern nur eine Teilmenge. Über den Parameter perpage und page kann entsprechend die Anzahl der Elemente pro Seite und die Seitenzahl angegeben werden. Zusätzlich kann die count Funktion genutzt werden, um die Anzahl aller Objekte zu erhalten.

curl "https://centralplanner.net/api/contacts/count" -H 'Authorization: Token token="my-api-token"'