Schlagwörter (tags) in CentralPlanner

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Kontakte Reservierungen

Sonstiges: Schlagwörter

Bei den Schlagwörter sowie den meisten sonstigen Objekten in CentralPlanner stehen die folgenden Actions zur Verfügung: index, show, create, update und delete. Jedes Schlagwort enthält die folgenden Felder:

Feldname Feldtyp Beschreibung
id INTEGER ID des Schlagwortes (Read only)
account_id INTEGER ID des Accounts (Read only)
contacts_count INTEGER) Anzahl der Personen, die das Schlagwort haben
name VARCHAR(60) Name des Schlagwortes
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)

Action: Index

GET /api/tags.json
Mit der Index Action kann eine Liste aller Schlagwörter in einem Account abgefragt werden. Als Default werden immer 50 Elemente ausgegeben. Die Zahl der Elemente pro Seite / Request kann über den Parameter perpage verändert werden. Durch Angabe des Parameters page (z.B. page=2) kann die Seitenzahl angegeben werden. Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created-at-asc" für absteigend nach Erstellungsdatum. Wenn das order Statement übergeben wird, ist die Sortierreihenfolge (asc, desc) eine Pflichtangabe. Sortiert werden kann nach created_at (Erstellungsdatum), updated_at (Bearbeitungsdatum) oder name (Alphabetisch). Standard ist asc (aufsteigend) nach name (Alphabet).

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

[{
    "id": 7,
    "account_id": 8,
    "contacts_count": 5,
    "name": "vegetarier",
    "created_at": "2014-07-11T16:13:35.000+02:00",
    "updated_at": "2014-07-11T16:13:59.000+02:00"
}, ...]

Action: Show

GET /api/tags/{id}
Die Show Funktion gibt alle Kontakte zurück, die mit dem Schlagwort versehen sind. Voraussetzung hierfür ist eine für den Account gültige Tag ID. Als Default werden immer 50 Elemente ausgegeben. Die Zahl der Elemente pro Seite / Request kann über den Parameter perpage verändert werden. Durch Angabe des Parameters page (z.B. page=2) kann die Seitenzahl angegeben werden. Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created-at-asc" für absteigend nach Erstellungsdatum. Wenn das order Statement übergeben wird, ist die Sortierreihenfolge (asc, desc) eine Pflichtangabe. Sortiert werden kann nach created_at (Erstellungsdatum), updated_at (Bearbeitungsdatum) oder name (Alphabetisch). Standard ist asc (aufsteigend) nach name (Alphabet).

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

[{
    "id": 949,
    "account_id": 8,
    "completed_bookings_count": 4,
    "title": null,
    "first": "Günther",
    "last": "Bäcker",
    "note": null,
    "phone": "",
    "phone2": null,
    "mail": "",
    "company": null,
    "street": null,
    "zip": null,
    "city": null,
    "newsletter": false,
    "created_at": "2011-08-31T11:55:17.000+02:00",
    "updated_at": "2013-05-15T16:56:25.000+02:00"
}, ...]

Action: Create

POST /api/tags.json
Ein neues Schlagwort kann mit der Action create angelegt werden. Im positiven Fall liefert das System das neue Schlagwort zurück. Zum Anlegen eines neuen Tags ist die Übergabe des Namens Pflicht.

Beispiel
curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-token"' 
-X POST https://centralplanner.net/api/tags 
-d '{"tag":{"name":"Mein Schlagwort"} }'

{
    "id": 7,
    "account_id": 8,
    "contacts_count": 0,
    "name": "Mein Schlagwort",
    "created_at": "2014-07-11T16:13:35.000+02:00",
    "updated_at": "2014-07-11T16:13:59.000+02:00"
}

Action: Update

PUT /api/tags/{id}.json
Analog zur Create Action funktioniert das Update. Hierzu ist das Verb PUT erforderlich und die Route muss die ID des zu bearbeitenden Elementes erhalten. Die Rückgabe ist hier nicht das Element selber, sondern der Header :ok mit dem HTTP Code 200.

Beispiel
curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="mein-api-key"' 
-X PUT https://centralplanner.net/api/tags/7 
-d '{"tag":{"last":"Mein neuer Tag Name"} }'

Status: 200 OK

Action: Delete

DELETE /api/tags/{id}.json
Zum Löschen eines Elementes muss man dieses über seine Route mit dem Verb DELETE ansprechen. Auch ist hier die Rückgabe der HTTP Code 200 mit dem Header :ok. Achtung: Bei dem löschen eines Tags wird dieses von allen Kontakten entfernt.

Beispiel
  curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-key"' 
-X DELETE https://centralplanner.net/api/tags/7 

Status: 200 OK

Sonderfunktionen der Schlagwörter

Action: Search

GET /api/tags/search.json?name=meinTag
Um nach einer oder mehreren Schlagwörtern zu suchen, können die Parameter first, last, phone, mail und/oder company übergeben werden. Wenn einer oder mehrere Treffer gefunden wurden, erfolgt die Rückgabe in gleicher Form, wie bei der Index Funktion. Wenn keine Treffer gefunden wurden geben wir einen leeren Array zurück.

Beispiel
curl "https://centralplanner.net/api/tags/search?name=vege" 
-H 'Authorization: Token token="my-api-key"'

[{
    "id": 7,
    "account_id": 8,
    "contacts_count": 5,
    "name": "vegetarier",
    "created_at": "2014-07-11T16:13:35.000+02:00",
    "updated_at": "2014-07-11T16:13:59.000+02:00"
}]