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 der Link-Header leer ist, befindet man sich auf der letzten Seite.


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'


Mehr zu API...
30 Tage gratis

Account sofort startbereit. Voller Funktionsumfang. Ohne Zahlungsangaben.