Damit das keine leere Floskel bleibt, beschreibe ich im Folgenden ein paar Tools und Vorgehensweisen, um die API von 1CRM und anderen Systemen zu testen und das Prinzip Web-API praxisorientiert zu verstehen.

Inhalt

Was ist eine Web-API?

Web-APIs gibt es eigentlich schon, seit es das WWW gibt. Über die Jahre haben sich mehrere Standards etabliert, der erste große war SOAP, über den XML-Dateien nach einem definierten Schema ausgetauscht werden konnten. Die REST-API, die ich hier beschreiben möchte, wird seit ein paar Jahren als De-facto-Standard beim Datenaustausch zwischen Apps und Server-Backends, oder auch bei der Server-zu-Server Kommunikation verwendet.

Was ist REST?

Die Einfachheit und Nachvollziehbarkeit ist der Kern von REST, kurz für Representational State Transfer. Objekte lassen sich mit REST über eindeutige, verständliche HTTP-Endpunkte ansprechen, in unserem Beispiel /api.php/data/Contact. Die Aktion, die ausgeführt werden soll, ist über die HTTP-Anfragemethode definiert, z. B. GET. Auch hier folgt die Funktionalität einer einfachen Logik:

  • GET holt Daten, das kennt jeder von einem normalen Webseitenaufruf im Browser; Adresse eingeben, Return drücken und schon macht der Browser einen GET Request auf die Adresse und zeigt das Ergebnis an.
  • POST sendet Daten und legt ein neues Objekt an. Auf normalen Webseiten wird POST verwendet, um Formulardaten an den Server zu senden.
  • PATCH ist beim normalen Internetsurfen eher selten, bei REST werden darüber Daten gesendet, um ein Objekt auf dem Server zu ändern.
  • PUT ist eine Mischung aus POST und PATCH, das Objekt wird falls vorhanden geändert, ansonsten neu angelegt.
  • DELETE löscht, wie der Name schon sagt ein Objekt.

Vorteile und Bedeutung von REST-APIs

Ein großer Vorteil und vermutlich auch der Grund, weshalb sich REST-basierte Web-Schnittstellen so weit verbreitet haben, ist die Einfachheit bei der Abfrage und dem Übermitteln von Daten.

Die große Bedeutung von REST liegt jedoch vor allem in seiner weiten Akzeptanz als Standard. Dies erleichtert zum einen die Vernetzung von verschiedenen Systemen, was im Zuge der Digitalisierung immer wichtiger wird. Und zum anderen werden REST-APIs häufig bereitgestellt, um die eigene Plattform für Erweiterungs-Entwicklerinnen und -Entwickler zu öffnen. Trello macht das zum Beispiel so und profitiert damit von zahlreichen zusätzlichen Features für seine Nutzerbasis, ohne selbst die eigene Plattform erweitern zu müssen.

Zukünftig könnten Graph-APIs, z.B. mit GraphQL eine größere Rolle spielen, die Ablösung von REST ist aber noch nicht absehbar.

Praxis-Beispiel REST: CRM-Kontakte einlesen, ändern und erstellen

Als Werkzeug zum Testen von REST-APIs verwende ich den Talend API Tester als Chrome-Erweiterung: https://chrome.google.com/webstore/detail/talend-api-tester-free-ed/aejoelaoggembcahagimdiliamlcdmfm. Da unsere CRM-Demo öffentlich verfügbar ist, zeige ich Ihnen in diesem Praxis-Beispiel, wie Sie über die REST-API von 1CRM Daten auslesen, verändern und hinzufügen können.

Für den Einstieg erstellen Sie einfach

  • einen neuen Request,
  • tragen https://demo.1crm.de/api.php/data/Contact  als Adresse ein
  • und klicken auf Add Authorization.

REST-API-Zugrff authorisieren

  • Tragen Sie die Zugangsdaten eines CRM-Benutzers ein. Für die 1CRM-Demo können Sie für dieses Beispiel den Admin-Nutzer Frau Maier mit den Zugangsdatenmaier/maier verwenden:

REST-API-Zugangsdaten eingeben

  • Danach einfach auf Send klicken.

Das Resultat sollte etwa wie folgt aussehen. Die Anwort 200 OK besagt, dass die Anfrage erfolgreich war. Rechts unten im Bild sehen Sie die Ergebnisse als JSON-Objekt:

REST-API gibt Antwort

CRM-Daten lesen mit GET

In Kombination mit dem Endpunkt ergeben sich folgende Möglichkeiten zum Lesen von Daten:

  • GET auf /api.php/data/Contact liefert eine Liste von Kontakten zurück.Als Parameter lassen sich u. a. Filter oder die Anzahl der gewünschten Objekte mitgeben. /api.php/data/Contact?limit=200&filter_text=Markus würde zum Beispiel bis zu 200 Kontakte mit Markus in Vor- oder Nachnamen anzeigen.filter_text entspricht dabei dem Textfilter in der Listenansicht von 1CRM.Weitere Informationen: https://demo.1crm.de/api.php#endpoint_dataList_get

 

  • GET auf /api.php/data/Contact/123 liefert den Kontakt mit der ID 123 zurück, falls vorhanden.
    (1CRM-IDs haben normalerweise 36 Stellen und sind alphanumerisch. Insofern geht die Chance auf einen Treffer gegen 0.) Gültige IDs können Sie aber unter anderem der vorhergehenden Abfrage oder der Adressleiste einer Detailansicht im 1CRM entnehmen. (In der Adressleiste gibt es immer einen Teil in der Form &record=69d132d8-8d86-8c95-6e4f-5e3cb7f64bf3, nach dem = bis zum Ende, oder bis zu einem & befindet sich die ID)Weitere Informationen: https://demo.1crm.de/api.php#endpoint_dataRecord_get

CRM-Daten hinzufügen mit POST

Zur Änderung von Daten (dazu gehört auch das Erstellen von Daten) müssen Sie immer, außer beim Löschen, ein JSON-Objekt mit Feldnamen und den zugehörigen Werten übermitteln. Mindestens die Pflichtfelder des Moduls müssen dabei definiert sein. Beim CRM-Kontakt ist das das Feld last_name.

Stellen Sie also in unserem Beispiel die Methode auf POST um und schreiben Sie in das Body-Feld die folgenden Werte ein:

{
"data":
{
"last_name": "Langstrumpf",
"first_name": "Pippi",
"salutation": "Ms.",
"email1": "pippi.langstrumpf@example.com"
}
}

Beim Senden erhalten Sie als Resultat eine ID. Unter dieser ID finden Sie jetzt in 1CRM eine Frau Pippi Langstrumpf.

CRM-Kontakt über die REST-API anlegen

CRM-Daten ändern mit PATCH

Die ID eines CRM-Kontaktes können Sie verwenden, um über die API Änderungen an einem vorhandenen Kontakt vorzunehmen. In meinem Fall mit einem PATCH auf /api.php/data/Contact/bfa396e6-0bc6-47e6-5995-5e3d60cb222f, denn beim Vornamen hatte ich unnötige „Datensparsamkeit“ betrieben:

{
"data":
{
"last_name": "Langstrumpf",
"first_name": "Pippilotta Viktualia Rollgardina Pfefferminz Efraimstochter",
"salutation": "Ms.",
"email1": "pippi.langstrumpf@example.com"
}
}

REST-API PATCH

 

Übersicht der wichtigsten REST-Methoden zum Ändern von Daten

Weitere CRM-Module über REST ansprechen

Die erste Frage, die jetzt kommt, ist wahrscheinlich: “Und was ist mit den anderen CRM-Modulen?”

Ganz einfach, führen Sie in Talend einfach einen GET-Request auf /api.php/meta/modules durch und voilà – eine lange Liste mit Modulen. In der API wird als Endpunkt immer das primary_model verwendet.

Die Liste der Felder zu einem Modul lassen sich für das Kontaktmodul über einen GET-Request auf /api.php/meta/fields/Contact abrufen. Die Antwort liefert Detailinformationen zu den einzelnen Feldern, zum Beispiel mögliche Werte von Dropdowns inklusive Übersetzung.

Abzufragende Felder lassen sich über den fields-Parameter im Listenendpunkt /api.php/data/Contact?fields[]=last_name&fields[]=primary_account mitgegeben.

In den Metadaten finden sich außerdem die möglichen Filter, die sich direkt ansprechen lassen. ?filters[any_email]=pippi.langstrumpf@example.com filtert zum Beispiel alle Mailfelder.

Was in den Metainformationen aktuell noch fehlt, sind die Relationen zwischen den Modulen, die Subpanels in 1CRM. Wir haben eine entsprechende Erweiterung für 1CRM erstellt und gehen davon aus, dass der Endpunkt /api.php/meta/links/Contact auch in eine der nächsten Versionen von 1CRM offiziell enthalten sein wird.

Die Funktionalität ist allerdings jetzt schon vorhanden. Mit /api.php/Contact/123/opportunities können Sie beispielsweise alle Chancen des Kontakts mit der ID 123 abrufen, siehe auch https://demo.1crm.de/api.php#endpoint_dataRelatedList_get.

Online-Hilfe: REST-API verwenden

Weitere Informationen zum Thema REST-API 1CRM

1CRM enthält die REST-API ab der Professional Edition. Weitere Informationen zur 1CRM-REST-API finden Sie in unserer Online-Dokumentation unter REST-API verwenden sowie im kanadischen Developer Guide auf 1crm.com.

Eine OpenAPI-Dokumentation und Scripte, um sie mithilfe von Microsoft Power Automate aus jedem 1CRM erstellen zu können, gibt es unter https://github.com/visual4/1crmOpenApi. Als Entwickler können Sie zum Beispiel die API-Client-Bibliothek von https://github.com/1CRM/1crm-api-client-php nutzen, um eine Integration zu programmieren.

Falls das nicht Ihre Welt ist, gibt es viele wunderbare Web-Apps, mit denen Sie eine Brücke bauen können (Microsoft Flow/ Power Automate, Zapier, NodeRed etc.) oder Anwendungen, mit denen Sie über die REST-API Daten weiterverarbeiten können (Excel mit PowerQuery, PowerBI…). Aber das sind Themen für viele weitere Artikel.

REST-APIs lassen sich vielerorts nutzen

Das Schöne an REST ist, dass Sie nach dieser kurzen Einführung nicht nur die REST-API von 1CRM verwenden können, sondern ebenfalls die APIs von anderen Systemen.

Um ein paar Beispiele zu nennen:

  • Mautic: https://developer.mautic.org/?php#contacts (der Endpunkt ist /api/contacts).
  • Salesforce: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm
  • Sipgate Teams Telefonanlagen: https://api.sipgate.com/v2/doc.
CRM-System einrichten
Prozessoptimierung