Grundlagen

Authentifizierung

Für die Authentifizierung wird der API-Schlüssel benötigt, den jeder MOCO-Nutzer in seinem Profil > Integrationen findet. Dieser Schlüssel muss in jedem Aufruf als sogenannter Authorization-Header enthalten sein. 

curl -X GET \
  'https://{domain}.mocoapp.com/api/v1/projects.json' \
  -H 'Authorization: Token token={api-key}'

API-Schlüssel via API

Es besteht auch die Möglichkeit, den API-Schlüssel direkt über die API abzufragen. Dies ist der einzige Aufruf, bei dem der Authorization-Header nicht übergeben wird. Stattdessen ist die Übermittlung von E-Mail und Passwort notwendig:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/session \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'email=max@muster.de&password=meinpasswort'

Die Antwort lautet wie folgt:

{
    "api_key": "3783278b83d83f3caa339393",
    "user_id": 12345678
}

Rate Limiting

Als sicheres Limit können 15 Abfragen innerhalb von 15 Sekunden angenommen werden. Anschliessend wird mit einem 429 (Too Many Requests) Status Code geantwortet.

Pagination

Die Antworten werden seitenweise (pagination) zurückgegeben. In der Regel sind 100 Einträge pro Anfrage enthalten. Über Header-Felder kann die Anzahl der Seiten abgefragt werden. Die URLs für die nächsten Seiten sind im Link-Header definiert:
  • X-Page – 3
  • X-Per-Page – 100
  • X-Total – 415
  • Link – <https://{domain}.mocoapp.com/api/v1/projects.json?page=4>; rel="next"

Folgendes Beispiel zeigt den Link-Header bei Abfrage der 3. Ergebnisseite:

Link: <https://{domain}.mocoapp.com/api/v1/projects.json?page=4>; rel="next"
Falls kein Link-Header mit rel="next" vorhanden ist, befindet man sich auf der letzten Seite.

Sortierung

Die Sortierung kann über den Parameter sort_by gesteuert werden und besteht aus dem Feldnamen und optional der Sortierreihenfolge (Standard: aufsteigend). Alle möglichen Sortierfelder sind in den jeweiligen Bereichen aufgelistet.

Beispiele:

sort_by=title
sort_by=date desc

Eigene Felder

MOCO unterstützt eigene Felder auf vielen Ressourcen. Diese sind auch über die API lesend und schreibend über das Attribut custom_properties verfügbar.

"custom_properties": {
    "UID": "123-UID-456",
    "Branche": "Automotive"
},

Die Parameter werden so übergeben, wie sie benannt sind:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/customers \
  -H 'authorization: Token token={api-key}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'name=Beispiel AG&currency=CHF&custom_properties[Branche]=Automotive'

Alle Werte werden als "String" übergeben, ausser für die "Mehrfachauswahl" wird ein Array erwartet:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/customers \
  -H 'authorization: Token token={api-key}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'custom_properties[Branchen][]=Automotive&custom_properties[Branchen][]=Banking'

  • Einzeilige Eingabe – "Automotive"
  • Mehrzeilige Eingabe – "Ein mehrzeiliger Inhalt..."
  • Link – "https://www..."
  • Ja/Nein – "0", "1" (0 = Nein, 1 = Ja)
  • Einfachauswahl – "Wert"
  • Mehrfachauswahl – "Wert"
ACHTUNG: Wenn eigene Felder beschrieben werden, müssen alle bestehenden Felder übermittelt werden, da sonst die nicht übermittelten entfernt werden.

WebHooks

Mithilfe von WebHooks können Integrationen in nahezu Echtzeit realisiert werden.  Ereignisse in MOCO werden dazu abonniert. Wenn eines dieser Ereignisse ausgelöst wird, sendet MOCO einen HTTPS-POST-Payload an die konfigurierte URL des WebHooks inkl. SHA256-Signatur des Payloads (So kann MOCO als Absender und die Integrität der Daten verifiziert werden). Zusätzliche Header-Angaben erlauben die Zuordnung des Payloads.

  • Payload via HTTPS-POST
  • Objekt via X-Moco-Target – (Activity, Customer, Project, ...)
  • Ereignis via X-Moco-Event – (create, update, delete, archive, ...)
  • Ereignis via X-Moco-Timestamp – (Zeitpunkt des Ereignisses)
  • Signatur via X-Moco-Signature
  • Der Empfänger muss innerhalb von 10 Sekunden bestätigen!

Folgendes Beispiel zeigen die Header bei einem neuen Zeiteintrag:

X-Moco-Target: Activity
X-Moco-Event: create
X-Moco-Timestamp: 1527170410463
X-Moco-Signature: f457bffc50e9b63f455ab107c55f2f61956550aa5525c2cfe07f574014bd8a9e

  • Diese Funktion steht erst nach der Testphase zur Verfügung.
  • Unter bestimmten Konstellationen (z.B. Downtime des Empfängers) können die Ereignisse in falscher Reihenfolge ankommen. Der Timestamp im Header kann hier als Prüfindikator dienen.

Mehr zu API...
30 Tage gratis

Account sofort startbereit. Voller Funktionsumfang. Ohne Zahlungsangaben.