Introduktion
API står för Application Programming Interface. Ett API gör att du kan interagera programmatiskt med vissa delar av RESPONSUM och utbyta information. RESPONSUM tillhandahåller API-endpoints för centrala funktioner/data som kan vara användbara för vissa automatiseringar och integrationer med andra (operativa) system/verktyg.
Dessa API-endpoints kommer att uppdateras/utökas över tid, men vi kommer att se till att de förblir bakåtkompatibla så att skapade integrationer fortsätter att fungera. Om du har frågor eller önskemål om nya endpoints, kontakta oss via support@responsum.eu.
Snabbstart
- Säkerställ att API:er är aktiverade för din tenant. De är inaktiverade som standard, så du kan behöva kontakta support@responsum.eu.
- När det är aktiverat kan du gå till settings > setup > my organization. Genom att klicka dig vidare på den översta nivån kan du hitta din “tenant key” i egenskaperna.
- Nu hittar du vår dokumentation under settings > integrations > API documentation
- Skapa en API-token genom att gå till settings > integrations > API tokens
- Det finns några kodexempel i Node.JS/JavaScript här: https://github.com/RESPONSUM-BE/RESPONSUM-api-example – Du kan använda tenant key + API-token som genererades tidigare för att testa.
- Du hittar ett diagram i vårt Help Center som förklarar de viktigaste begreppen i RESPONSUM. Det hjälper dig att förstå vår grundstruktur så att du enkelt kan hitta tillbaka till begreppen.
- Här är en snabb introduktion till några viktiga begrepp – du kan läsa mer ingående om dem nedan.
- UUID:er: Du kan skapa egna UUID:er eller generera RESPONSUM-formaterade med hjälp av
https://api.responsum.app/v1/[tenant key]/uuids/[amount]– Om du genererar egna UUID:er, se absolut till att de är 100 % unika. Det finns bibliotek om du behöver dem; använd inte math.random 🙂 - Länkobjekt: RESPONSUM använder INTE typisk relationsbaserad modellering. Länkar mellan objekt är objekt för oss.
- Versionshantering: Nästan alla RESPONSUM-modeller är versionshanterade. Det innebär att vi spårar ändringar för allt. Det finns vissa specifika API:er för att hantera detta eller begära information om ett objekts versionshistorik och godkännande.
- Beräknade fält: RESPONSUM beräknar server-side ett antal fält. Det sker automatiskt. När du hämtar ett objekt skickar vi även våra beräknade fält. Du kan inte uppdatera dem manuellt.
- Händelsedrivet: Allt som händer i RESPONSUM (skapa, uppdatera, ta bort, version, …) börjar som en händelse. Du kan använda webhooks för att prenumerera på alla möjliga händelser. I praktiken kan allt som händer i RESPONSUM hanteras via webhook-API:er.
- UUID:er: Du kan skapa egna UUID:er eller generera RESPONSUM-formaterade med hjälp av
- Det rekommenderas alltid att läsa hela manualen innan du ger dig ut. Det är en farlig värld där ute och du vill inte skada dig – men med den här snabbstarten hoppas jag att du får det att fungera. Lycka till!
Kom igång
Säkerställa att API:et är aktiverat för din tenant
Som standard är RESPONSUM API inaktiverat på tenant-nivå och dolt i vårt gränssnitt.
För att aktivera API:et för din tenant behöver du kontakta vårt supportteam via support@responsum.eu, som kan aktivera det och även besvara frågor du fortfarande kan ha efter att ha läst den tillgängliga dokumentationen, samt sätta dig i kontakt med rätt personer för mer tekniska frågor, diskussioner eller implementeringsönskemål.
All vidare dokumentation förutsätter att RESPONSUM API har aktiverats för din tenant.
Din tenant key
När du använder RESPONSUM API måste du använda din faktiska tenant key, så som den är definierad i vårt system, i varje request. Denna tenant key hittar du i applikationen genom att navigera till settings > setup > my organization och öppna den högsta organisatoriska enheten där, eftersom den motsvarar din tenant.
I tenantens detaljer för ”Meta data” (två pilar nedåt högst upp i sidopanelen) hittar du det skrivskyddade fältet ”Tenant key”.

Denna tenant key sattes när din tenant skapades och kan, till skillnad från tenantnamnet, inte ändras och är unik för just denna tenant.
OpenAPI-specifikationer för din tenants API
RESPONSUM API som du kommer att använda genereras specifikt för din tenant och inkluderar eventuella anpassningar (anpassade fält, anpassade relationer, affärsregler…) som kan ha gjorts. Därför kan de modeller som tillhandahålls skilja sig mellan tenants.
För att underlätta integration tillhandahåller vi en json-specifikationsfil enligt OpenAPI Specifications. Du kan läsa in den genom att ersätta [tenant key] i följande url med din egen tenant key som du hittade tidigare: https://api.responsum.app/v1/[tenant key]/spec.json.
Vi tillhandahåller även en visuell dokumentation baserad på denna specifikationsfil för att möjliggöra enklare testning medan du bekantar dig med API:et. Den finns i vår app om du navigerar till settings > integrations > API Documentation.
Den första requesten i den API-dokumentationen är också att hämta OpenAPI-specifikationerna och är en av de få requests du kan göra utan autentisering.
Autentisering och auktorisering
Alla funktionella requests till RESPONSUM API förväntar sig att en API-token skickas med som en del av requesten. Den fungerar både som autentisering (genom att kontrollera själva token) och auktorisering (genom att kontrollera behörigheterna för användarkontot som är kopplat till token) (länken till användarens behörighetsnivå).
Alla åtgärder som utförs via API:et med denna token loggas också som utförda av användaren som är kopplad till API-tokenen. Du agerar alltså som den användaren när du använder API-tokenen.
Skapa en API-token
API-tokens kan endast hanteras via vår app genom att gå till settings > integrations > API Tokens.
En API-token består av:
- Ett namn för att du enkelt ska känna igen den i listan och skilja tokens åt;
- En tokensträng, genererad åt dig och som ska användas i varje request till API:et;
- En användarbehörighetsnivå, kopplad till ett användarkonto som kommer att efterliknas när denna API-token används. Om du vill ge eller neka behörigheter för denna API-token gör du det genom att ge eller neka dem för användarkontot som är länkat här;
- Ett utgångsdatum; om detta är satt kommer tokenen inte längre att fungera efter detta datum.
När den har skapats ska tokensträngen i en API-token vara tillgänglig för användning direkt. Om din tokensträng av någon anledning komprometteras kommer en regenerering av tokensträngen och sparande av den uppdaterade API-tokenen att ogiltigförklara den gamla tokensträngen omedelbart.
Skicka API-token i requests
När du har en giltig API-tokensträng kan du skicka den till RESPONSUM API genom att lägga till en extra header i dina requests Api-Token vars värde är din API-tokensträng.
Hjälp-/utility-requests
UUID:er
Det finns olika standarder för Universally Unique IDentifiers som används i dag, och RESPONSUM API bör acceptera de flesta, eftersom vår validering består av:
- Minst 5 tecken långt
- Består endast av tecknen:
- a till z:
abcdefghijklmnopqrstuvwxyz - 0 till 9:
0123456789 - bindestreck:
-
- a till z:
Dessutom förväntar vi oss att UUID:et är unikt, men vi gör endast begränsad kontroll av detta, i den meningen att ett försök att skapa en ny modell eller länkar med ett UUID som redan finns för den specifika modellen eller länken kommer att ge ett fel.
RESPONSUM använder själv en variant av cuid2-algoritmen, modifierad för att vara lättare att känna igen och för att passa vårt föredragna format.
För att göra det enklare för dig att använda UUID:er som följer detta RESPONSUM-format har vi lagt till en API-endpoint som du kan använda för att generera mellan 1 och 1000 UUID:er som garanterat är unika och omöjliga att skilja från de som genereras internt av RESPONSUM.
Ersätt tenant key och antal i https://api.responsum.app/v1/[tenant key]/uuids/[amount] och gör en GET-request, och se till att inkludera headern Api-Token. Som returvärde får du en JSON-array som innehåller UUID:erna som strängvärden.
Exempelprojektet innehåller en exempeloperation som gör detta: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getUuids.ts
Länkar
Länkformat och generell princip
Länkar i RESPONSUM hanteras lite annorlunda än de flesta vanliga lösningar, eftersom varje länk lagras som ett eget objekt i länksamlingen och refererar till de olika modeller som länkas samman, i stället för att modellerna har referenser som länkar till andra modeller.
Länkar uppdateras heller aldrig; de kan bara skapas eller tas bort, eftersom en ändring av en länkad modell betraktas som att den gamla länken tas bort och en ny länk skapas.
Länkdefinitioner
Alla länkar baseras på olika länkdefinitioner. Vissa är hårdkodade och vissa kan användarskapas. När du hämtar länkdefinitionerna via GET-endpointen https://api.responsum.app/v1/[tenant key]/link-definitions får du en JSON som innehåller ett stort objekt, vilket kan ses som en ordlista över alla länkdefinitioner.
Ett exempelsnippet som referens:
{
"stakeholder-stakeholderContact-contacts": {
"stakeholder": {
"modelType": "stakeholder",
"oneOrMany": "one",
"isRequired": false,
"relationBehaviour": "reference-same-object"
},
"contact": {
"modelType": "stakeholder-contact",
"oneOrMany": "many",
"isRequired": false,
"relationBehaviour": "reference-same-object"
}
},
<snipped-for-size>
}
En linkType är en unik beskrivande nyckel för just denna länkdefinition. I detta exempel kan du se att varje objektnyckel (”stakeholder-stakeholderContact-contacts”) är den specifika länkdefinitionens linkType.
En role är en beskrivande nyckel, unik inom länkdefinitionen, för att identifiera de olika grenarna i länkdefinitionen. I detta fall är “stakeholder” och “contact” de två rollerna. Som du ser behöver dessa inte matcha modeltypen. Ett annat exempel är en självrefererande länk, där rollerna kan vara “parent” och “child”.
Observera också att även om de flesta länkar bara har två grenar, är fler än två tillåtna och vi har redan minst ett fall där vi har trevägslänkar.
Under rollen finns en branch definition, som beskriver vissa egenskaper för just denna gren:
- modelType beskriver vilka modelTypes som är tillåtna. Det kan vara:
- En enda modelType
- En array av modelTypes
- Konstanten “all-models”
- oneOrMany beskriver om det bara ska vara tillåtet med en länk för denna kombination av model type och uuid, eller om det kan finnas många
- isRequired beskriver om denna länk krävs på denna sida av länken. Om true ska varje modell av den/de typer som definieras i modelType ha minst en länk av denna linkType
- relationBehaviour används främst internt för att avgöra vad som ska göras med denna länk när modeller dupliceras.
Länkobjekt
Baserat på länkdefinitionen ovan kan vi hitta samma sak i faktiska länkar.
Ett exempel på ett länkobjekt kan se ut så här:
{
"uuid": "0fc0ea83-88df-49ec-a681-1ced0a6c0683",
"type": "link",
"linkType": "stakeholder-stakeholderContact-contacts",
"links": [
{
"modelType": "stakeholder",
"modelUuid": "55092a14-4d95-4665-ac50-eb687e535222",
"role" : "stakeholder"
},
{
"modelType": "stakeholder-contact",
"modelUuid": "ad95eded-3168-4a12-968d-456bc031af7e",
"role" : "contact"
}
]
}
Egenskaperna uuid och type “link” finns alltid på varje objekt för att unikt identifiera det.
linkType matchar en av länkdefinitionerna, i detta fall den i exemplet för länkdefinitioner.
Egenskapen links är en array med de olika grenarna. Antalet objekt i denna array kommer alltid att matcha antalet roller i länkdefinitionen, eftersom vi för varje roll förväntar oss en länkad modell.
- role matchar en av rollerna som definieras i den matchande länkdefinitionen
- modelType matchar en av de tillåtna model types för den matchande länkdefinitionen och rolldefinitionen
- uuid identifierar sedan vilken specifik modell av den angivna modeltypen som denna länk refererar till
Dessutom kan det finnas en egenskap metaData som kan innehålla ett fritt dataobjekt med extra metadata om just denna länk, även om detta sällan används.
Direkta länkrequests
För det mesta får du länkar som en del av modeller, och på samma sätt skapar eller ändrar du länkar när du skapar eller uppdaterar modeller.
En länkeigenschaft på en modell, när den är ifylld, kommer att betraktas som den nya listan med länkar för den egenskapen och ersätter eventuella redan befintliga länkar för modellens egenskap. När du lägger till en ny länk till en modell ska du därför även inkludera eventuella befintliga länkar som du vill behålla.
Utöver detta finns det även tre endpoints för att interagera med länkar direkt.
GET-endpointen https://api.responsum.app/v1/[tenant key]/links gör att du kan hämta alla länkar filtrerade med flera filter:
- uuids, uuid:erna för länkobjekten
- model-uuids, uuid:erna för modellerna som refereras i länkobjekten
- relation-names, linkTypes för länkobjekten
Dessa kan anges som query-parametrar som innehåller en json-strängarray som värden.
POST-endpointen https://api.responsum.app/v1/[tenant key]/create, som främst används för att skapa modeller, accepterar även länkobjekt och kan därmed användas för att skapa nya länkar.
DELETE-endpointen https://api.responsum.app/v1/[tenant key]/link gör att du kan ta bort en eller flera länkar direkt, för vilka du känner till länkobjektets uuid.
Modellrequests
All data i RESPONSUM lagras i modeller, och därför kommer de flesta API-operationer att göras mot dessa modeller.
Varje modell måste ha en type och uuid, båda är obligatoriska och kan inte ändras efter att de har skapats.
Type är en av våra fördefinierade modeller, till exempel ”processing-activity” eller ”risk”.
Modelldefinition
Detta avser en modelldefinition med alla tillgängliga fält, inklusive de anpassade som definierats i applikationen. För type kommer den att innehålla den förväntade typen som en sträng; se till att använda exakt dessa strängvärden.
För grundfält kommer den att innehålla deras datatyp och om de är obligatoriska eller inte.
För länkfält kommer den att innehålla en array av länkobjekt.
Lista modeller
För varje modeltyp har vi en separat GET-endpoint i API:et för att hämta alla eller en filtrerad lista av modeller för den typen.
För filtrering kan du lägga till en URI-kodad query-parameter “param-filter” till GET-url:en som innehåller ett JSON-objekt med filtret. Detta filter har som egenskap namnet på den egenskap du vill filtrera på och som värde en array med alla egenskapsvärden du vill matcha mot.
Om du till exempel vill filtrera ”advice” för att hitta modeller där status är “new” eller “ongoing”, skapar du ett json-filterobjekt så här: {"status": ["new", "ongoing"]}. Därefter URI-kodar du det som värde för param-filter-query-parametern, vilket ger dig en GET-request enligt följande: https://api.responsum.app/v1/[tenant key]/advice?param-filter=%7B%22status%22%3A%20%5B%22new%22%2C%20%22ongoing%22%5D%7D
Du kan också kombinera filter på flera egenskaper genom att lägga till extra egenskaper i json-filterobjektet, så här: {"status": ["new", "ongoing"], "isObsolete": [false]}. Detta returnerar en array med matchande modeller eller en tom array om inga modeller hittas.
Exempelprojektet innehåller en exempeloperation som gör detta: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getCountriesByFilter.ts
Hämta en enskild modell
För varje modeltyp har vi en separat GET-endpoint i API:et för att hämta en specifik modell för den typen, baserat på dess uuid. Lägg bara till uuid:et till modeltypens url, vilket ger dig en GET-request enligt följande: https://api.responsum.app/v1/[tenant key]/advice/raou8qtt-60od-n7t5-g8el-c0sy99r0ppag
Detta returnerar den enskilda modellen eller ett 404-fel ‘no model found’.
Skapa modeller (och länkar)
För att skapa modeller och länkar mellan dessa har vi en generisk POST-endpoint https://api.responsum.app/v1/[tenant key]/create, eftersom vi vill göra det möjligt att skapa en uppsättning av flera relaterade modeller och länkarna mellan dem i ett enda steg, för att minska risken för ofullständiga uppsättningar på grund av misslyckad validering eller liknande.
Create-endpointen accepterar en array av modeller, där varje modell ska ha type, uuid och eventuella obligatoriska egenskaper för den modeltypen.
För länkegenskaperna på modellerna kan du även inkludera en array av länkobjekt, där vi tar unionen över de tillhandahållna modellerna och infogar dessa. Det innebär att om du har två modeller som länkar till varandra kräver vårt API bara att länkobjektet som kopplar ihop de två finns på en av modellerna för att förstå att det ska läggas till; att lägga till det på båda modellerna gör ingen skillnad.
Exempelprojektet innehåller en exempeloperation som gör detta.
Uppdatera modeller (och länkar)
För att uppdatera modeller och länkar mellan dessa har vi en generisk PATCH-endpoint https://api.responsum.app/v1/[tenant key]/update, eftersom vi vill göra det möjligt att uppdatera en uppsättning av flera relaterade modeller och länkarna mellan dem i ett enda steg.
Update-endpointen accepterar en array av modeller, där varje modell endast ska ha type, uuid och de fält som uppdateras.
För länkegenskaperna på modellerna är dessa återigen en array av länkobjekt, där vi tar unionen över de tillhandahållna modellerna och sedan tar bort alla länkar som inte ingår i denna union, innan vi lägger till eventuella länkar i unionen som ännu inte finns i databasen. Det innebär att om du vill lägga till en länk till en modellegenskap ska du även inkludera länkobjekten för den befintliga modellegenskapen, annars kommer dessa befintliga länkar att tas bort.
Exempelprojektet innehåller en exempeloperation som gör detta.
Versionshantering av modeller
De flesta RESPONSUM-modeller har versionshantering aktiverad, vilket innebär att varje ändring som görs i dessa modeller registreras och att dessa versioner kan frysas och godkännas osv.
Hämta alla versioner för en modell
Du kan hämta alla versionsändringar för en given modell med följande GET-request: https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]. Detta returnerar både ”unversioned” (utkast) och varje fryst version med extra information om versionen, såsom versionsstatus, vem som skapade versionen, vem som godkände den, osv.
Versionens livscykel
Oversionerade ändringar
Alla ändringar börjar som oversionerade ändringar. Varje gång en modell skapas eller uppdateras registrerar vi det tidigare och nya värdet för de ändrade egenskaperna. Vem som gjorde ändringen och när, samt vilken typ av operation det var.
Listan över operationer har några vanliga värden såsom ’create’, ’update’, ’delete’, ’merge’, ’import’, ’history-restoration’ och ’update-link’ men kan också innehålla specialvärden såsom ’V2-create’ för vår legacy-import, och när som helst kan nya värden läggas till beroende på framtida utveckling.
Frys
När som helst kan ändringarna för en modell frysas med POST https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/freeze, vilket skapar en ny version med reviewStatus ’frozen’ och inkluderar eventuella oversionerade ändringar som fanns. Om det inte fanns några oversionerade ändringar skapas ingen ny version.
Du kan också ange ett versionsnamn vid frysning, men om inget anges kommer ett att beräknas baserat på de versioner som redan finns.
Vid denna punkt kan vissa personer med rätt behörighet redan godkänna eller avslå denna version, men det viktigaste är att alla nya ändringar kommer att läggas till som oversionerade ändringar, medan ändringar i denna version aldrig kommer att ändras.
Begär godkännande
För att få en version godkänd eller avslagen kan du begära att specifika personer granskar den. För detta kan du göra PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/request-approval med en versions-uuid och ”accountable user”-uuid. Detta triggar notiser till personen för att granska versionen och antingen godkänna eller avslå.
Godkänn eller avslå
Du kan också godkänna eller avslå versioner via API:et om användaren som är kopplad till din token har tillräckliga behörigheter.
Detta kan göras med de två PUT-endpoints https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/approve eller https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/reject, vilket återigen kräver versions-uuid:et som du vill godkänna eller avslå.
Webhooks
Ibland vill du också bli notifierad när modeller skapas eller uppdateras. För detta har vi webhooks som du kan konfigurera genom att gå till settings > integrations > webhooks.
För att underlätta användning kan webhooks aktiveras eller inaktiveras; endast aktiverade webhooks triggar anrop.
Namnet används enbart för att skilja webhooks åt.
Den angivna URL:en kommer att anropas med de angivna headers. Detta blir en POST-request som innehåller en json-body med changeAction, modelType och uuids (en array av uuids).
Du kan välja bland följande change actions; endast för de valda kommer webhooken att anropas:
- ’link-deleted’: när en länk tas bort från en eller flera av egenskaperna
- ’link-created’: när en länk läggs till för en eller flera av egenskaperna
- ’item-deleted’: när objektet tas bort
- ’item-meta-data-updated’: när beräknade egenskaper uppdateras, t.ex. senast uppdaterad av, granskningsstatus, osv.
- ’item-base-data-updated’: när bas-egenskaperna uppdateras, t.ex. namn, isObsolete, osv.
- ’item-created’: när objektet skapas
Du kan välja den delmodul som webhooken ska trigga för; detta kan vara så specifikt som en enskild modeltyp eller så brett som varje modell i applikationen.
Baserat på vår interna logik kan du få flera webhook-anrop för samma modelType och uuid med kort mellanrum efter att en användare sparar. Att till exempel lägga till en länk och sätta en egenskap triggar ett ‘item-base-data-updated’, ‘item-meta-data-updated’ och ‘link-created’-anrop.
Exempelapplikation
https://github.com/RESPONSUM-BE/RESPONSUM-api-example
Se readme för att komma igång. När du har fått den att köra och öppnar http://localhost:3000 bör du se något i stil med detta:

När du sedan utför de olika operationerna kommer du att se en logg över operationerna på höger sida av sidan.
Du hittar också alla dessa operationer i mappen src\operations\