REST API

REST API-et lar din egen programvare gjøre det appen gjør: prosjekter og målingene deres, mapper og produktkatalogen; med Enterprise organisasjonen din, slik siden Enterprise styrer den; med Open Guest gjestelenken din, gjesteprosjekter og tilbudsforespørsler. Det svarer i JSON. Den fullstendige referansen, med alle felt og eksempler, er API-dokumentasjonen; denne siden er oversikten.

For å åpne dokumentasjonen fra appen går du til codeUtvikler > apiREST API og trykker menu_bookSe dokumentasjon.

Base-URL#

Alle forespørsler går til:

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

Autentisering#

Send API-nøkkelen din, uendret, i Authorization-headeren i hver forespørsel. Opprett nøkkelen på siden Utvikler: se API-nøkler.

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

Hver forespørsel kontrolleres mot nøkkelens tilgang (for eksempel Prosjekter Lese), abonnementet ditt og, for en forespørsel sendt fra en nettside, nøkkelens nettstedsbegrensninger. Hold nøkler som kan endre data, på serveren din: se hold nøkkelen din trygg.

Live og sandbox#

Det er én base-URL for begge. Nøkkelen avgjør: en sandbox-nøkkel leser og skriver sandbox-prosjekter, -mapper og -produkter, som live-nøkler aldri ser. Organisasjonens brukere, plasser og team er de samme i begge, så for å endre dem trenger du en live-nøkkel. Gjesteprosjekter laget med en sandbox-nøkkel faktureres aldri, og sandbox-prosjekter kan ikke bygges inn på nettstedet ditt. Tokens oppgir miljøet de tilhører.

Hva API-et dekker#

Noen ting å vite:

• En nøkkel når prosjektene på sin egen konto og, med Enterprise, prosjektene til organisasjonens brukere.
• Å slette et prosjekt legger det i Papirkurv, som i appen, og bare den som opprettet det, kan gjøre det; slett det for godt fra Papirkurv med forever=true. Å slette en mappe legger prosjektene i den i Papirkurv.
• I et prosjekts målinger lister en figur produktene sine i productIds, i rekkefølge; productId er det første av dem.
• /projects/{pid}/mmp gir den samme .mmp-filen som appen eksporterer. Skjemaet er publisert på github.com/blueblinkone/mmp-validator. Nye elementer legges bare til som valgfrie, så en leser skrevet for en eldre fil fortsetter å fungere.
• Med Open Guest teller et gjesteprosjekt som er startet via API-et (POST /open-guest/projects), med i Open Guest-bruken og -budsjettet ditt, som et som er startet fra gjestelenken din.
• På Open Guest har delen person_pin_circleGjestelenke veiledningen Open Guest API, med kode for serveren og siden din: serveren din henter et token fra POST /auth/token med live-nøkkelen din og sender den besøkende til et nytt prosjekt av eget, med opplysningene deres utfylt.
• Folk kommer bare inn i organisasjonen din via invitasjon (POST /enterprise/invitations), som på siden Enterprise: den som ikke har en konto, får en og velger selv passordet. API-et oppretter aldri en konto og setter aldri et passord.
• Når du fjerner en bruker (POST /enterprise/users/{uid}/remove), beholder vedkommende kontoen; når du sletter en (DELETE /enterprise/users/{uid}), slettes kontoen. Uansett blir arbeidet vedkommende har laget, hos organisasjonen, i en ny mappe med navnet til vedkommende som administratorene dine deler.
• Når en gjest ber om tilbudet ditt, svarer GET /open-guest/requests/{pid} med hvem gjesten er, hva vedkommende skrev, hva vedkommende målte og, med Produkter: Lese, selve tilbudet.
• På Open Guest starter tokens gjesteprosjekter for de besøkende. POST /auth/iframe/token, som logger en besøkende på et innebygd kart, er for Enterprise-nøkler.
• Produkter slettes aldri gjennom API-et, bare arkiveres, og et produkts kostpris returneres aldri.
• Matrikkeltomter er ikke en del av API-et.

Svar og feil#

En vellykket forespørsel svarer med status 200 og JSON (.mmp-eksporten svarer med XML). En mislykket svarer med en feilstatus og en body som denne:

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

Prøv API-et fra siden Utvikler#

codeUtvikler > terminalPrøv API-et sender ekte forespørsler med nøkkelen din og viser nøyaktig hva som kommer tilbake.

1. Velg Live eller Sandbox.
2. Velg et Endepunkt, for eksempel «List opp prosjektene dine», «Hent målinger» eller «Hent kontoen». Listen tilbyr endepunktene planen din inneholder.
3. Fyll inn parameterne. Et prosjekt eller et produkt velges med navn blant dem nøkkelen kan lese; der en person trengs, fylles din egen konto inn for deg.
4. Trykk play_arrowSend forespørsel. Statusen og svaret vises nedenfor.

Bare forespørsler som leser, tilbys, så ingenting endres ved å prøve, og disse forespørslene telles ikke i bruken din. Hvis nøkkelen din ikke har tilgangen et endepunkt trenger, advarer siden om at det vil svare 403.

Webhooks#

En webhook forteller serveren din når noe skjer, slik varslingse-postene forteller deg det. Webhooks er en del av planene Enterprise og Open Guest.

Sett opp en webhook#

I codeUtvikler > webhookWebhooks:

1. Skriv Endepunkt-URL: en https://-adresse på internett. Adresser på private nettverk avvises, og dette kontrolleres på nytt før hver levering.
2. Kryss av for Hendelser du vil ha (se hendelser). Et nytt endepunkt starter med hendelsene planen din sender, og minst én må være avkrysset.
3. Trykk saveLagre. Første gang viser siden Signeringshemmelighet i sin helhet. Kopier den da: etterpå vises bare de siste tegnene.
4. Trykk sendSend testhendelse og velg en hendelse.

En test sender et eksempel på den hendelsen, med oppdiktede verdier og "test": true i data, til det lagrede endepunktet ditt, selv når hendelsen ikke er avkrysset eller endepunktet er slått av. For å stoppe alle leveringer trykker du delete_outlineFjern: endepunktet og hemmeligheten slettes.

Under innstillingene har Webhook-referanse det du trenger for å skrive mottakersiden: headerne og body, kode som kontrollerer signaturen i Node.js, Python og PHP, og eksempeldata for hver hendelse.

Hva serveren din mottar#

Hver hendelse er én POST til endepunktet ditt, med en JSON-body:

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

id er unik for hver hendelse, created er når den skjedde i millisekunder siden 1. januar 1970 (UTC), og hva data inneholder, avhenger av hendelsen. Forespørselen har også disse headerne:

• Svar med en 2xx-status innen 8 sekunder, før du gjør noe tregt arbeid. Alle andre statuser, en omdirigering eller en tidsavbrudd regnes som en feil.
• Hver hendelse sendes én gang og forsøkes aldri på nytt. Delen viser Siste levering og Påfølgende feil.
• Etter 10 feil på rad slås endepunktet av, og eieren får en e-post. Rett opp serveren din og trykk saveLagre for å slå det på igjen.
• Av og til kommer en hendelse to ganger eller i feil rekkefølge. Bruk id for å ignorere gjentakelser og created for å sette hendelsene i rekkefølge.

Kontroller signaturen#

Alle som kjenner adressen din, kan sende til den, så kontroller hver levering før du stoler på den:

1. Del X-MMO-Signature-headeren ved kommaet i t og v1.
2. Beregn en HMAC-SHA256 av t, et punktum og den rå forespørselsbodyen, med signeringshemmeligheten din som nøkkel, skrevet som heksadesimalt.
3. Sammenlign resultatet med v1 med en sammenligning i konstant tid.
4. Avvis leveringen hvis t ligger mer enn 5 minutter fra nåtiden. t er i millisekunder.

Bruk bodyen akkurat slik den kom: å parse JSON-en og skrive den ut igjen endrer den, og signaturen stemmer ikke lenger.

autorenewRoter hemmelighet bytter ut hemmeligheten med en gang og viser den nye i sin helhet, én gang. Oppdater serveren din så snart du roterer.

Hendelser#