REST API

REST API'et lader din egen software gøre det, appen gør: projekter og deres målinger, mapper og produktkataloget; med Enterprise din organisation, som siden Enterprise styrer den; med Open Guest dit gæstelink, gæsteprojekter og anmodninger om tilbud. Det svarer i JSON. Den fulde reference, med alle felter og eksempler, er API-dokumentationen; denne side er overblikket.

For at åbne dokumentationen fra appen går du til codeUdvikler > apiREST API og trykker på menu_bookSe dokumentationen.

Base-URL#

Alle forespørgsler går til:

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

Godkendelse#

Send din API-nøgle, som den er, i headeren Authorization i hver forespørgsel. Opret nøglen på siden Udvikler: se API-nøgler.

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

Hver forespørgsel kontrolleres mod nøglens adgang (for eksempel Projekter Læs), dit abonnement og, for en forespørgsel sendt fra en webside, nøglens begrænsninger for websteder. Opbevar nøgler, der kan ændre data, på din server: se hold din nøgle sikker.

Live og sandbox#

Der er én base-URL til begge. Nøglen afgør det: en sandboxnøgle læser og skriver sandboxprojekter, -mapper og -produkter, som livenøgler aldrig ser. Din organisations brugere, pladser og teams er de samme i begge, så for at ændre dem skal du bruge en livenøgle. Gæsteprojekter oprettet med en sandboxnøgle faktureres aldrig, og sandboxprojekter kan ikke indlejres på dit websted. Tokens oplyser, hvilket miljø de tilhører.

Hvad API'et dækker#

Nogle ting er godt at vide:

• En nøgle når projekterne på sin egen konto og med Enterprise dem, der tilhører organisationens brugere.
• Når du sletter et projekt, kommer det i Papirkurv, som i appen, og kun dets opretter kan gøre det; slet det for altid fra Papirkurv med forever=true. Når du sletter en mappe, kommer dens projekter i Papirkurv.
• I et projekts målinger angiver en figur sine produkter i productIds i rækkefølge; productId er det første af dem.
• /projects/{pid}/mmp giver den samme .mmp-fil, som appen eksporterer. Dens skema er udgivet på github.com/blueblinkone/mmp-validator. Nye elementer tilføjes kun som valgfrie, så en læser skrevet til en ældre fil bliver ved med at virke.
• Med Open Guest tæller et gæsteprojekt, der er startet via API'et (POST /open-guest/projects), med i dit Open Guest-forbrug og -budget, ligesom et, der er startet fra dit gæstelink.
• På Open Guest har afsnittet person_pin_circleGæstelink vejledningen Open Guest API med kode til din server og din side: din server henter et token fra POST /auth/token med din livenøgle og sender den besøgende til et nyt projekt til dem selv, med deres oplysninger udfyldt.
• Folk kommer kun ind i din organisation via invitation (POST /enterprise/invitations), som på siden Enterprise: den, der ikke har en konto, får en og vælger selv sin adgangskode. API'et opretter aldrig en konto og angiver aldrig en adgangskode.
• Når du fjerner en bruger (POST /enterprise/users/{uid}/remove), beholder vedkommende sin konto; når du sletter en (DELETE /enterprise/users/{uid}), slettes kontoen. Uanset hvad bliver det arbejde, vedkommende har lavet, hos organisationen i en ny mappe med vedkommendes navn, som dine administratorer deler.
• Når en gæst beder om dit tilbud, svarer GET /open-guest/requests/{pid} med, hvem gæsten er, hvad vedkommende skrev, hvad vedkommende målte og, med Produkter: Læs, selve tilbuddet.
• På Open Guest starter tokens gæsteprojekter til dine besøgende. POST /auth/iframe/token, som logger en besøgende ind på et indlejret kort, er til Enterprise-nøgler.
• Produkter slettes aldrig via API'et, kun arkiveres, og et produkts kostpris returneres aldrig.
• Matrikelparceller er ikke en del af API'et.

Svar og fejl#

En vellykket forespørgsel svarer med status 200 og JSON (eksporten af .mmp svarer med XML). En mislykket svarer med en fejlstatus og en tekst som denne:

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

Prøv API'et fra siden Udvikler#

codeUdvikler > terminalPrøv API'en sender rigtige forespørgsler med din nøgle og viser præcis, hvad der kommer tilbage.

1. Vælg Live eller Sandbox.
2. Vælg et Endpoint, for eksempel "Vis dine projekter", "Hent målinger" eller "Hent kontoen". Listen tilbyder de endpoints, dit abonnement omfatter.
3. Udfyld dets parametre. Et projekt eller et produkt vælges ved navn blandt dem, nøglen kan læse; hvor der skal bruges en person, er din egen konto udfyldt for dig.
4. Tryk på play_arrowSend anmodning. Status og svaret vises nedenunder.

Der tilbydes kun forespørgsler, der læser, så intet ændres ved at prøve, og forespørgslerne tæller ikke med i dit forbrug. Hvis din nøgle ikke har den adgang, et endpoint kræver, advarer siden dig om, at det vil svare 403.

Webhooks#

En webhook fortæller din server, når der sker noget, ligesom notifikationsmails fortæller dig det. Webhooks er en del af abonnementerne Enterprise og Open Guest.

Opsæt en webhook#

I codeUdvikler > webhookWebhooks:

1. Skriv din Endpoint-URL: en https://-adresse på internettet. Adresser på private netværk afvises, og det kontrolleres igen før hver levering.
2. Afkryds de Hændelser, du vil have (se hændelser). Et nyt endpoint starter med de hændelser, dit abonnement sender, og mindst én skal være afkrydset.
3. Tryk på saveGem. Første gang viser siden din Signeringshemmelighed i sin helhed. Kopiér den dér: bagefter vises kun dens sidste tegn.
4. Tryk på sendSend testhændelse, og vælg en hændelse.

En test sender et eksempel på den hændelse, med opdigtede værdier og "test": true i dens data, til dit gemte endpoint, selv når hændelsen ikke er afkrydset, eller endpointet er slået fra. For at stoppe alle leveringer skal du trykke på delete_outlineFjern: endpointet og dets secret slettes.

Under indstillingerne har Webhook-reference det, du skal bruge for at skrive den modtagende side: headerne og body, kode der kontrollerer signaturen i Node.js, Python og PHP, og eksempeldata for hver hændelse.

Hvad din server modtager#

Hver hændelse er ét POST til dit endpoint med en JSON-body:

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

id er unik for hver hændelse, created er, hvornår den skete, i millisekunder siden 1. januar 1970 (UTC), og hvad data indeholder, afhænger af hændelsen. Forespørgslen har også disse headere:

• Svar med en 2xx-status inden for 8 sekunder, før du går i gang med noget langsomt. Enhver anden status, en omdirigering eller en timeout tæller som en fejl.
• Hver hændelse sendes én gang og forsøges aldrig igen. Afsnittet viser Seneste levering og Fejl i træk.
• Efter 10 fejl i træk slås endpointet fra, og ejeren får en e-mail. Ret din server, og tryk på saveGem for at slå det til igen.
• En gang imellem kommer en hændelse to gange eller i forkert rækkefølge. Brug id til at ignorere gentagelser og created til at sætte hændelser i rækkefølge.

Kontrollér signaturen#

Alle, der kender din adresse, kan sende til den, så kontrollér hver levering, før du stoler på den:

1. Del headeren X-MMO-Signature ved kommaet i t og v1.
2. Beregn en HMAC-SHA256 af t, et punktum og den rå forespørgselsbody, med din signing secret som nøgle, skrevet som hexadecimal.
3. Sammenlign resultatet med v1 med en sammenligning i konstant tid.
4. Afvis leveringen, hvis t ligger mere end 5 minutter fra det aktuelle tidspunkt. t er i millisekunder.

Brug body præcis som den ankom: hvis du parser JSON'en og skriver den ud igen, ændres den, og signaturen passer ikke længere.

autorenewRoter hemmelighed erstatter secret med det samme og viser den nye i sin helhed, én gang. Opdater din server, så snart du roterer.

Hændelser#