Guide

Kom i gang

Tre trekk tar deg fra ingenting til en ekte post i din egen terminal: skaff en legitimasjon, bytt den i et tilgangstoken, kall API-et. Denne siden slutter med at du har gjort det kallet.

Alt er ren HTTPS og JSON over standard OAuth 2.0, så et hvilket som helst språk med en HTTP-klient fungerer — og eksemplene under trenger ikke annet enn curl og et skall. Les siden én gang fra ende til ende, og du har formen på hvert kall du noen gang sender til Partner API; guidene etter denne fyller inn detaljene.

Hele flyten i tre trekk

Det er ingen håndtrykk å forhandle, ingen SDK å installere og ingen sesjon å holde i live. En legitimasjon identifiserer integrasjonen din, et token beviser den en stund, og tokenet autoriserer hvert kall. Det som først og fremst skiller trekkene, er hvor lenge det de gir deg varer — og det avgjør hvor du skal oppbevare det.

1. Skaff en legitimasjon. Et par av clientId og hemmelighet, opprettet inne i kundens Visena-instans av en administrator der. Det identifiserer integrasjonen din og avgjør hvilken bruker kallene opptrer som — se Legitimasjon og tokener.
2. Bytt den i et tilgangstoken. Én standard OAuth 2.0-forespørsel med client_credentials mot /{instanceName}/auth/api/v1/token gir et kortlevd bearer-token med nøyaktig de rettighetene du ba om. Det finnes ikke noe refresh-token: når det utløper, spør du på nytt.
3. Kall API-et. Send tokenet som Authorization: Bearer på hvert kall. Opprett, les, oppdater, slett, list og synkroniser — konvensjonene er de samme for alle ni ressursene, og Å gjøre kall dekker dem.

Dette trenger du før du starter

Fire verdier, og du har alle før du skriver en linje kode. Hvert eksempel på denne siden bruker plassholderne i høyre kolonne, så du kan bytte ut dine egne én gang og kopiere resten ordrett.

Selve legitimasjonen opprettes av en administrator i kundens egen instans, under Admin → Tilgangskontroll → Administrer API-tilganger. Har noen allerede gitt deg en klient-ID og en hemmelighet, har du alt denne siden trenger; hvis ikke er Legitimasjon og tokener siden du sender dem til.

En 60-sekunders smakebit

Fire kommandoer i en terminal: sett verdiene dine, bytt legitimasjonen i et token, og les den første siden med personer i instansen. Ingenting opprettes eller endres, og tokenet ber bare om read, så dette er trygt å kjøre mot en instans i drift.

Sett verdiene dine

Bytt inn de tre verdiene fra tabellen over. Hemmeligheten leses fra en ledetekst i stedet for å skrives inn i kommandoen, slik at den aldri havner i kommandohistorikken.

# The values from the table above — substitute your own.
export VISENA_BASE_URL="https://api.visena.example"
export VISENA_INSTANCE="acme"
export CLIENT_ID="acme-partner-3f9a"

# Prompt for the secret, so it stays out of your shell history.
read -rs -p "Client secret: " CLIENT_SECRET && echo
export CLIENT_SECRET

Hent et tilgangstoken

Token-endepunktet tar legitimasjonen over HTTP Basic — formen som hører hjemme i produksjon — og standardgrantet client_credentials. scope er obligatorisk og har ingen standardverdi: si nøyaktig hva tokenet får gjøre.

curl -sS -X POST "$VISENA_BASE_URL/$VISENA_INSTANCE/auth/api/v1/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=read"

{
  "access_token": "dcrEUVpMEpYqbdsDKawBb1yTqIAELMgqIO4KrN…",
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 86399
}

Tokenet er ugjennomsiktig — ikke tolk det — og lever i expires_in sekunder. Legg merke til at svaret gjentar den scope som faktisk ble gitt; det er verdien det er verdt å sjekke i en test. En integrasjon i produksjon henter ett token, mellomlagrer det og henter et nytt like før det utløper, og Legitimasjon og tokener viser det med en mellomlagring du kan kopiere.

Gjør kallet

Lim inn access_token fra svaret og send det som et bearer-token. Stien bærer instansnavnet, API-versjonen og en locale, og så ressursen — person, i entall, som hver ressurs i API-et.

# Paste the access_token from the response above.
export ACCESS_TOKEN="dcrEUVpMEpYqbdsDKawBb1yTqIAELMgqIO4KrN…"

# The first page of people in this instance.
curl -sS "$VISENA_BASE_URL/$VISENA_INSTANCE/api/v1/en/person?offset=0&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "totalItems": 428,
  "totalPages": 22,
  "page": 0,
  "size": 20,
  "items": [
    { "id": "xK9mQ2",
      "firstName": "Kari",
      "lastName": "Nordmann",
      "primaryEmail": "kari.nordmann@example.com",
      "isActive": true },
    …19 more…
  ],
  "links": { "self": "…", "next": "…/person?offset=20&limit=20" }
}

Det er hele modellen: legitimasjon → token → kall. Id-ene er ugjennomsiktige strenger som xK9mQ2 — lagre dem nøyaktig som du fikk dem og send dem tilbake ordrett, i stedet for å tolke eller konstruere dem.

Hvis det første kallet ikke virker

Feil er maskinlesbare, og de fem under dekker nesten hvert førsteforsøk. Token-endepunktet svarer med standard OAuth 2.0-feilkropp; API-et selv svarer med et problemdokument etter RFC 9457.

Alle de andre statuskodene, feltene i problemdokumentet du bør logge, og en gjentakelsesstrategi som ikke gjør vondt verre, står i Feil og feilsøking.

Når det kallet er besvart, er resten detaljer. Tre sider, i den rekkefølgen de fleste team vil ha dem:

Å gå gjennom et helt datasett eller synkronisere bare det som er endret, står i Lister, paginering og synk; hvert endepunkt på hver ressurs står i API-referansen; og før du peker en integrasjon mot produksjon, gå gjennom Sette i produksjon.