Hvordan bruke API-et og finne riktig "scope" for forespørsler
Når du jobber med Webtemp API, som i eksempelet med AbsenceReport, handler prosessen stort sett om tre viktige steg: vite hva slags informasjon du vil hente, finne riktig tilgang (scope) for å få tak i den informasjonen, og sende en korrekt forespørsel.
1. Hva er API-forespørsler?
En API-forespørsel er en måte å spørre systemet om informasjon eller be det utføre en oppgave. I Webtemp API-et kan forespørslene handle om å hente rapporter, oppdatere informasjon om kandidater, eller annet. I dette eksempelet bruker vi en forespørsel om fraværsrapport (AbsenceReport), men prinsippet er det samme for alle forespørsler.
2. Hva er et "scope" og hvorfor er det viktig?
Et scope er en type tilgang som gir tillatelse til å gjøre visse ting i systemet. For eksempel trenger du riktig scope for å kunne hente informasjon om fravær eller annen sensitiv informasjon. Når du sender en API-forespørsel, må du vite hvilke scopes du trenger for å få tilgang til akkurat den informasjonen.
I dette tilfellet, for å hente en fraværsrapport, trenger du scopes som lar deg lese rapportdata og informasjon om kunder. Eksempler på disse scope er:
https://api.webtemp.no/auth/report:all.orders.readhttps://api.webtemp.no/auth/customer:all.showcustomer.read
Dette betyr at du som bruker trenger riktig tilgangsnøkkel (token) med disse scope for å kunne gjennomføre forespørselen.
3. Slik sender du en forespørsel:
Når du har riktig scope, må du sende en forespørsel med nødvendig informasjon. Her er et eksempel på hvordan en forespørsel om en fraværsrapport kan se ut:
{
"candidateIds": [0],
"firmId": 0,
"includeSickLeave": true,
"includeVacation": true,
"fromTime": "2019-08-24T14:15:22Z",
"toTime": "2019-08-24T14:15:22Z",
"strictlyLimitToRange": true,
"useTheseTypesForSickLeave": [0],
"useTheseCodesForSickLeave": [0],
"useTheseCodesForVacation": [0]
}
I dette eksempelet hentes sykefravær og ferie for spesifikke kandidater i en bestemt tidsperiode. Her må du gi riktig candidateId (kandidatens ID) og firmId (firmaets ID) som obligatoriske felter. Du må også spesifisere om du vil inkludere sykefravær eller ferie, samt hvilke perioder du ønsker å rapportere på.
4. Svar fra API-et:
Når forespørselen sendes, vil API-et gi deg tilbake informasjonen i JSON-format, som kan leses og brukes til videre behandling. Svarene gir detaljerte data om de kandidatene du har bedt om, slik som perioder med sykefravær eller ferie.
Oppsummert:
Uansett hvilken forespørsel du ønsker å gjøre via API-et, følger prosessen disse stegene:
- Definer hva du vil hente: Vet du hvilken informasjon eller handling du trenger, f.eks. en fraværsrapport eller kandidatdetaljer?
- Finn riktig scope: Finn ut hvilke scopes du trenger for å få tilgang til informasjonen eller utføre handlingen.
- Send riktig forespørsel: Formater forespørselen med korrekt informasjon og send den til API-et.
Dette prinsippet gjelder for alle typer API-kall, enten du jobber med rapporter, oppdaterer kandidatdata, eller noe annet.