Version 2.0 · /api/v2
Hier findest du wichtige Grundlagen über die Verwendung unserer API wie z.B. Authentifizierung.
Die Basis-URL der API beinhaltet die Subdomain deines Grip-Kontos. Alle Resourcen bzw. deren Pfade beziehen sich auf diese Basis-URL.
https://deinkonto.getgrip.de/api/v2
Sämtliche Endpunkte der API erfordern eine Authentifizierung der Requests. Die Authentifizierung erfolgt mit Hilfe eines API Tokens.
curl -H 'Authorization: Token token="{token}"' \
https://getgrip.de/api/v2/client_organizations
Bitte ersetze {token} mit dem API Token deines Grip-Kontos. Das Token findest du unter Konto-Einstellungen > REST API. Wende dich ggf. an den Konto-Inhaber oder einen Benutzer mit Administratorrechten.
Die Schnittstelle folgt weitgehend der JSON:API-Konvention. Diese legt fest, wie ein Client den Abruf oder die Änderung von Ressourcen anfordert und wie ein Server auf diese Anforderungen reagieren sollte. JSON:API ist darauf ausgelegt, sowohl die Anzahl der Anfragen als auch die Menge der zwischen Clients und Servern übertragenen Daten zu minimieren. Diese Effizienz wird erreicht, ohne die Lesbarkeit, Flexibilität oder Auffindbarkeit zu beeinträchtigen. Grundsätzliche Informationen dazu liefert die JSON:API-Spezifikation.
Der JSON:API Media Type ist application/vnd.api+json.
Objekte, die miteinander in einer Beziehung stehen, werden gemäß der JSONAPI Spezifikation als "relationships"
dargestellt. So führt bspw. ein client die ID der dazugehörigen client_organization unter
"relationships" auf.
{
"data": {
"id": "153",
"type": "client",
"attributes": {
"firstname": "Sophie",
"lastname": "Klarmann",
"prefix": "",
"sex": 2,
"phone": "",
"email": "",
"notes": "",
"created_at": "2022-04-12T18:22:12.380+02:00",
"updated_at": "2023-03-10T18:05:26.351+01:00"
},
"relationships": {
"client_organization": {
"data": {
"id": "110",
"type": "client_organization"
}
}
}
}
}
Es ist auch möglich, einen Schritt weiter zu gehen und die verbundenen Objekte im selben Request anzufordern. Dies wird mit dem Request-Parameter include={Objektbezeichnung} erreicht.
curl -H 'Authorization: Token token="{token}"' \
https://getgrip.de/api/v2/client_organizations/110?include=clients
{
"data": {
"id": "110",
"type": "client_organization",
"attributes": {
"name": "Klarmann Audio GmbH",
// ...
},
"relationships": {
"clients": {
"data": [
{
"id": "187",
"type": "client"
},
{
"id": "153",
"type": "client"
}
]
}
}
},
"included": [
{
"id": "187",
"type": "client",
"attributes": {
"firstname": "Marcello",
"lastname": "Antonucci",
// ...
},
"relationships": {
"client_organization": {
"data": {
"id": "110",
"type": "client_organization"
}
}
}
},
{
"id": "153",
"type": "client",
"attributes": {
"firstname": "Sophie",
"lastname": "Klarmann",
// ...
},
"relationships": {
"client_organization": {
"data": {
"id": "110",
"type": "client_organization"
}
}
}
}
]
}
Dies ist eine Liste mit den verschiedenen Kategorien von Statuscodes, die von der API zurückgegeben werden. Daran lässt sich erkennen, ob eine Anfrage erfolgreich war.
Die Kundenorganisation ist die rechtliche Einheit, der ein Angebot unterbreitet wird. Sie enthält einen oder mehrere Kunden als Ansprechpartner. Beispiele: Unternehmen, Freiberufler, Handwerksbetrieb, Verein, Stiftung, Praxis, Kanzlei, Behörde etc.
Kunden sind Ansprechpartner, also Personen, innerhalb der Kundenorganisation. Sie benötigen immer eine Kundenorganisation als Container. Empfänger eines Angebots in Grip ist immer der Ansprechpartner, also ein Kunde.
© 2024 T8 Lab GmbH