API-dokumentation

InSurvey tillhandahåller ett öppet, självdokumenterande API baserat på OpenAPI (Swagger). Det innebär att ni alltid har tillgång till en aktuell och interaktiv beskrivning av alla tillgängliga endpoints – direkt i webbläsaren. I den här artikeln går vi igenom var ni hittar dokumentationen, hur den är uppbyggd och hur ni kommer igång med era första anrop.

Var hittar jag dokumentationen?

Den interaktiva dokumentationen (Swagger UI) når ni på följande adress:

https://api.insurvey.com/

OpenAPI-specifikationen

Vill ni generera en klient eller importera API:et i ett annat verktyg (t.ex. Postman eller Insomnia) hittar ni den råa OpenAPI-specifikationen i JSON-format här:

https://api.insurvey.com/swagger/v1/swagger.json

Så är dokumentationen uppbyggd

• Endpoints – varje rad motsvarar ett anrop (t.ex. GET, POST) med en kort beskrivning.
• Parametrar – obligatoriska och valfria fält beskrivs, inklusive datatyp och var de skickas (i sökväg, query eller anropskropp).
• Scheman (Models) – strukturen på det data ni skickar in och får tillbaka.
• Svarskoder – vilka HTTP-statuskoder ett anrop kan returnera.
• Prova själv – med knappen Try it out kan ni skicka riktiga anrop direkt från dokumentationen.

Autentisera dig mot API:et

De flesta endpoints kräver att ni är inloggade. Autentiseringen sker i två steg: först loggar ni in med en serviceanvändare för att få en token, sedan skickar ni med den token i efterföljande anrop.

1. Logga in och hämta en token

Skicka era uppgifter (e-post och lösenord för serviceanvändaren) till inloggnings-endpointen:

<code>POST /auth/login

{
  "email": "din-serviceanvandare@exempel.se",
  "password": "••••••••"
}

Svaret innehåller en autentiseringstoken som ni använder i nästa steg. Läs mer om hur ni skapar och hanterar inloggningsuppgifter i vår artikel om serviceanvändare.

2. Skicka med din token i anropen

Ange sedan din token i varje efterföljande anrop, antingen via X-Auth-Token-headern:

X-Auth-Token <din-token>

Testa direkt i Swagger UI

Eftersom X-Forward-Host och X-Auth-Token är egna headers som inte kan sättas direkt i Swagger UI rekommenderar vi att ni använder ett verktyg för att modifiera headers, exempelvis ett webbläsartillägg. Då skickas headerna automatiskt med i alla anrop.

1. Installera ett verktyg för att modifiera headers, t ex som ett webbläsartillägg.
2. Lägg till headern X-Forward-Host med er instans som värde, t.ex. ert-kundnamn.insurvey.com.
3. Öppna https://api.insurvey.com i webbläsaren.
4. Använd POST /auth/login för att hämta en token.
5. Kopiera din token och lägg till den som X-Auth-Token i ert header-verktyg.
6. Välj valfri endpoint, klicka på Try it out, fyll i eventuella parametrar och klicka på Execute.

Versionshantering

API:et publiceras som version v1. Vissa endpoints kan vara markerade som obsolete (utfasade) i dokumentationen – undvik att bygga nya integrationer mot dessa. Vi rekommenderar att ni regelbundet kontrollerar dokumentationen, eftersom den alltid speglar den senast driftsatta versionen.

Vanliga frågor

Jag får statuskod 401 – vad gör jag?

En 401 Unauthorized betyder oftast att din token saknas, har fel format eller har gått ut. Kontrollera att ni skickar med  X-Auth-Token och hämta vid behov en ny token via /auth/login.

Jag får statuskod 403 – vad gör jag?

En 403 Forbidden betyder att ni är inloggade men saknar behörighet för endpointen. Kontrollera serviceanvändarens roller och behörigheter.

Relaterade artiklar

• Användare i InSurvey
• Hantera behörigheter