REST-API

Mit der REST-API kann Ihre eigene Software lesen und ändern, was sich in Ihrem Konto bei Measure Map Online befindet: Projekte und ihre Messungen, Ordner, den Produktkatalog und, bei Enterprise, die Mitglieder Ihrer Organisation. Sie antwortet in JSON. Die vollständige Referenz mit jedem Feld und Beispiel ist die API-Dokumentation; diese Seite gibt den Überblick.

Um die Dokumentation aus der App zu öffnen, gehen Sie zu codeEntwickler > apiREST-API und klicken Sie auf menu_bookDokumentation anzeigen.

Basis-URL#

Jede Anfrage geht an:

https://api.measuremaponline.com/api/v2

Authentifizierung#

Senden Sie Ihren API-Schlüssel unverändert im Header Authorization jeder Anfrage. Erstellen Sie den Schlüssel auf der Seite „Entwickler“: siehe API-Schlüssel.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Jede Anfrage wird gegen den Zugriff des Schlüssels (zum Beispiel Projekte Lesen), Ihr Abonnement und, bei einer Anfrage aus einer Webseite, die Website-Einschränkungen des Schlüssels geprüft. Bewahren Sie Schlüssel, die Daten ändern können, auf Ihrem Server auf: siehe Ihren Schlüssel schützen.

Live und Sandbox#

Für beide gibt es dieselbe Basis-URL. Der Schlüssel entscheidet: Ein Sandbox-Schlüssel liest und schreibt Sandbox-Projekte, -Ordner und -Produkte, die Live-Schlüssel nie sehen. Mitglieder sind in beiden dieselben, aber um sich als Mitglied anzumelden, brauchen Sie einen Live-Schlüssel. Gastprojekte, die mit einem Sandbox-Schlüssel angelegt werden, werden nie abgerechnet, und Sandbox-Projekte lassen sich nicht auf Ihrer Website einbetten. Tokens geben an, zu welcher Umgebung sie gehören.

Was die API abdeckt#

Einige Punkte, die Sie wissen sollten:

• Ein Schlüssel erreicht die Projekte seines eigenen Kontos und, bei Enterprise, die der Mitglieder der Organisation.
• Ein Projekt oder einen Ordner über die API zu löschen ist endgültig: Nichts landet im Papierkorb. Ein Ordner nimmt die Ordner und Projekte darin mit, die zu Ihrem Konto oder zu Ihren Mitgliedern gehören.
• In den Messungen eines Projekts listet eine Form ihre Produkte in productIds auf, in ihrer Reihenfolge; productId ist das erste davon.
• /projects/{pid}/mmp liefert dieselbe .mmp-Datei, die die App exportiert. Ihr Schema ist unter github.com/blueblinkone/mmp-validator veröffentlicht. Neue Elemente kommen nur als optionale hinzu, sodass ein Programm, das für eine ältere Datei geschrieben wurde, weiter funktioniert.
• Bei Open Guest zählt ein über die API erstelltes Projekt mit der Zugriffsebene Open Guest zu Ihrer Open-Guest-Nutzung und zu Ihrem Budget, wie eines, das über Ihren Gastlink gestartet wurde.
• Bei Open Guest enthält der Abschnitt person_pin_circleGastlink die Anleitung Open-Guest-API mit Code für Ihren Server und Ihre Seite: Ihr Server holt mit Ihrem Live-Schlüssel ein Token von POST /auth/token und schickt den Besucher zu einem neuen eigenen Projekt, in dem seine Angaben schon eingetragen sind.
• Wenn Sie mit POST /users/new ein Mitglied anlegen, belegt das einen Platz, wie eine Einladung, und das Mitglied erhält die Standardrolle Ihrer Organisation.
• Ein Token von POST /auth/{uid}/login öffnet das Konto dieses Mitglieds. Dafür ist daher ein Schlüssel nötig, der Mitglieder ändern darf, niemals der Schlüssel in Ihren Einbettungen. Für einen Administrator oder einen Manager wird es nicht ausgegeben, ebenso wenig mit einem Sandbox-Schlüssel.
• Produkte werden über die API nie gelöscht, nur archiviert, und der Einkaufspreis eines Produkts wird nie zurückgegeben.
• Katasterparzellen sind nicht Teil der API.

Antworten und Fehler#

Eine erfolgreiche Anfrage antwortet mit Status 200 und JSON (der .mmp-Export antwortet mit XML). Eine fehlgeschlagene antwortet mit einem Fehlerstatus und einem Inhalt wie:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

Die API auf der Seite „Entwickler“ ausprobieren#

codeEntwickler > terminalAPI ausprobieren sendet echte Anfragen mit Ihrem Schlüssel und zeigt genau, was zurückkommt.

1. Wählen Sie Live oder Sandbox.
2. Wählen Sie einen Endpunkt, etwa „Alle Projekte auflisten“ oder „Messungen abrufen“.
3. Füllen Sie seine Parameter aus. Ein Projekt oder Produkt wählen Sie nach Namen aus denen, die der Schlüssel lesen kann; wo eine Person gebraucht wird, wird Ihr eigenes Konto für Sie eingetragen.
4. Klicken Sie auf play_arrowAnfrage senden. Status und Antwort erscheinen darunter.

Es werden nur lesende Anfragen angeboten, sodass beim Ausprobieren nichts geändert wird, und diese Anfragen zählen nicht zu Ihrer Nutzung. Wenn Ihr Schlüssel nicht den Zugriff hat, den ein Endpunkt braucht, warnt die Seite Sie, dass er mit 403 antworten wird.

Webhooks#

Ein Webhook teilt Ihrem Server mit, wenn etwas geschieht, so wie die Benachrichtigungs-E-Mails es Ihnen mitteilen. Webhooks gehören zu den Tarifen Enterprise und Open Guest.

Einen Webhook einrichten#

Unter codeEntwickler > webhookWebhooks:

1. Geben Sie Ihre Endpunkt-URL ein: eine https://-Adresse im Internet. Adressen in privaten Netzwerken werden abgelehnt, und das wird vor jeder Zustellung erneut geprüft.
2. Setzen Sie die Häkchen bei den gewünschten Ereignisse (siehe Ereignisse). Ein neuer Endpunkt beginnt mit den Ereignissen, die Ihr Tarif sendet, und mindestens eines muss angehakt sein.
3. Klicken Sie auf saveSpeichern. Beim ersten Mal zeigt die Seite Ihr Signatur-Secret vollständig an. Kopieren Sie es dann: Danach werden nur noch seine letzten Zeichen angezeigt.
4. Klicken Sie auf sendTestereignis senden und wählen Sie ein Ereignis.

Ein Test sendet ein Beispiel dieses Ereignisses mit erfundenen Werten und "test": true in seinem data an Ihren gespeicherten Endpunkt, auch wenn das Ereignis nicht angehakt oder der Endpunkt ausgeschaltet ist. Um alle Zustellungen zu beenden, klicken Sie auf delete_outlineEntfernen: Der Endpunkt und sein Geheimnis werden gelöscht.

Unter den Einstellungen enthält die Webhook-Referenz alles, was Sie zum Schreiben der Empfangsseite brauchen: die Header und den Inhalt, Code zum Prüfen der Signatur in Node.js, Python und PHP sowie Beispieldaten für jedes Ereignis.

Was Ihr Server erhält#

Jedes Ereignis ist ein POST an Ihren Endpunkt mit einem JSON-Inhalt:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id ist für jedes Ereignis eindeutig, created ist der Zeitpunkt des Ereignisses in Millisekunden seit dem 1. Januar 1970 (UTC), und was data enthält, hängt vom Ereignis ab. Die Anfrage hat außerdem diese Header:

• Antworten Sie innerhalb von 8 Sekunden mit einem 2xx-Status, vor jeder langsamen Verarbeitung. Jeder andere Status, eine Weiterleitung oder eine Zeitüberschreitung gilt als Fehlschlag.
• Jedes Ereignis wird einmal gesendet und nie wiederholt. Der Abschnitt zeigt die Letzte Zustellung und die Aufeinanderfolgende Fehler.
• Nach 10 Fehlschlägen in Folge wird der Endpunkt ausgeschaltet, und der Eigentümer erhält eine E-Mail. Beheben Sie das Problem auf Ihrem Server und klicken Sie auf saveSpeichern, um ihn wieder einzuschalten.
• Hin und wieder kommt ein Ereignis doppelt oder in falscher Reihenfolge an. Verwenden Sie id, um Wiederholungen zu ignorieren, und created, um die Ereignisse zu ordnen.

Die Signatur prüfen#

Jeder, der Ihre Adresse kennt, kann an sie senden. Prüfen Sie daher jede Zustellung, bevor Sie ihr vertrauen:

1. Teilen Sie den Header X-MMO-Signature am Komma in t und v1.
2. Berechnen Sie einen HMAC-SHA256 aus t, einem Punkt und dem unveränderten Inhalt der Anfrage, mit Ihrem Signatur-Secret als Schlüssel, in hexadezimaler Schreibweise.
3. Vergleichen Sie das Ergebnis mit v1, mit einem Vergleich in konstanter Zeit.
4. Lehnen Sie die Zustellung ab, wenn t mehr als 5 Minuten von der aktuellen Zeit abweicht. t ist in Millisekunden angegeben.

Verwenden Sie den Inhalt genau so, wie er angekommen ist: Wenn Sie das JSON einlesen und wieder ausgeben, ändert er sich, und die Signatur passt nicht mehr.

autorenewSecret erneuern ersetzt das Secret sofort und zeigt das neue einmal vollständig an. Aktualisieren Sie Ihren Server, sobald Sie es erneuern.

Ereignisse#