Så bygger du din första applikation mot DirSys API med hjälp av Claude AI

Så bygger du din första applikation mot DirSys API med hjälp av Claude AI

Så bygger du din första applikation mot DirSys API med hjälp av Claude AI

API: DirSys Public API v1.0.0 · Verktyg: Claude Code för Windows · Nivå: Nybörjare

Om guiden

Guiden visar hur du kommer igång med DirSys Public API utan att först behöva sätta dig in i API:ets alla endpoints och scheman manuellt. I stället låter du Claude Code läsa API:ets OpenAPI-specifikation åt dig och skapa en fungerande applikation utifrån den.

Som genomgående exempel bygger vi en applikation som listar informationsbärare från DirSys Security. Metoden är dock inte specifik för den resursen – samma tillvägagångssätt fungerar lika bra för personuppgiftsbehandlingar i DirSys Integrity och för övriga delar av API:et. Byt ut resursnamnet i prompten i steg 7; i övrigt följer du samma steg.

Du behöver inte ha programmerat tidigare för att följa guiden, men det underlättar om du vet ungefär vilket programmeringsspråk eller vilken typ av applikation (skript, webbsida eller skrivbordsapp) du vill skapa. Om du är osäker kan du be Claude Code om förslag.

Det här bygger du i guiden

En enkel applikation som listar informationsbärare med namn, säkerhetsutrymme och datum för senaste uppdatering. Data hämtas direkt från DirSys API när applikationen körs. Programmeringsspråk och gränssnitt avgörs av vad du skriver i prompten till Claude Code i steg 7.

Informationsbärare
Kundregister CRM
Säkerhetsutrymme: IT-drift
Uppdaterad 2024-03-12
Personalakter
Säkerhetsutrymme: HR
Uppdaterad 2024-01-08
Ekonomisystem
Säkerhetsutrymme: Ekonomi
Uppdaterad 2024-02-27
Kundtjänstloggar
Säkerhetsutrymme: Support
Uppdaterad 2023-11-30

Så fungerar flödet

När du bygger appen behöver du inte arbeta direkt mot DirSys API. Claude Code läser specifikationen och skriver koden. Därefter är det den färdiga applikationen som anropar API:et med din nyckel.

Steg 1–5
Developer Portal
Du skapar en API-klient, kopierar nyckeln och laddar ner OpenAPI-specifikationen
→
Steg 6–7
Claude Code
Läser OpenAPI-specifikationen och din prompt och skriver applikationen åt dig
→
Resultat
DirSys API
api.dirsys.app

Applikationen som Claude Code bygger anropar DirSys API direkt och använder din API-nyckel som Bearer-token. Vad appen får se och göra styrs helt av nyckelns behörigheter (scopes) och vilka säkerhetsutrymmen eller controllers den har åtkomst till – inte av vad du skriver i prompten.

Förutsättningar

  • Ett DirSys-konto med behörighet att skapa API-klienter i Developer Portal.
  • Alternativet "API access (Developer portal)" måste vara aktiverat för din användarroll. Inställningen finns under Användaradministration → Roller och behörigheter. Utan den kommer du inte in i Developer Portal, oavsett vilka övriga behörigheter du har – se steg 1.
  • Claude Code för Windows installerat på din dator.
  • Grundläggande datorvana. Du behöver inte kunna programmera sedan tidigare.

Steg 1 – Kontrollera att din roll har åtkomst till Developer Portal

Innan du loggar in kontrollerar du att alternativet API access (Developer portal) är inställt på Yes. Du hittar inställningen under Användaradministration → Roller och behörigheter för den roll som du eller din administratör har tilldelat dig.

Observera

Om inställningen redan är aktiverad för din roll kan du hoppa direkt till steg 2. Om du inte själv har behörighet att ändra roller behöver du be en administratör att aktivera den åt dig.

Steg 2 – Logga in i Developer Portal

Öppna Developer Portal och ange ditt Organization ID (Tenant ID) i inloggningsrutan.

Du omdirigeras därefter till inloggningssidan för er egen tenant. Ditt Organization ID finns i den information som ni fick när ert DirSys-konto skapades.

Steg 3 – Skapa en API-klient

Under API Clients skapar du en ny klient. Fyll i ett namn och ta ställning till tre saker: vilka behörigheter (scopes) klienten ska ha, vilken anropsfrekvens den behöver och vilka delar av er data den ska kunna nå.

FältInnebörd
PermissionsREAD och/eller WRITE. En applikation som bara ska läsa data – som exemplet i den här guiden – behöver enbart READ.
Rate LimitStandard är 100 anrop/minut. Räcker inte det, kontakta support@dirsys.com.
Access RestrictionsUnrestricted ger åtkomst till alla säkerhetsutrymmen och controllers, även sådana som läggs till senare.Restricted begränsar klienten till de du väljer.
Ge nyckeln minsta möjliga behörighet

En applikation som bara ska visa data behöver aldrig WRITE-behörighet. Om den dessutom bara ska läsa data för en viss avdelning väljer du Restricted och anger rätt säkerhetsutrymme i stället för Unrestricted.

Steg 4 – Kopiera API-nyckeln

När klienten har skapats visas den nya API-nyckeln i formatet dfk_<prefix><token>. Kopiera den direkt och spara den på en säker plats.

Nyckeln visas bara en gång

Om du lämnar sidan utan att kopiera nyckeln går den inte att visa igen. Då behöver du skapa en ny API-klient. Om du tappar bort nyckeln spärrar du den gamla klienten så att nyckeln inte kan missbrukas.

Steg 5 – Ladda ner OpenAPI-specifikationen

På klientens sida finns en länk till API-referensen, där du kan ladda ner hela specifikationen för DirSys Public API som OpenAPI-dokument i JSON- eller YAML-format.

Formatet spelar ingen roll för Claude Code – båda beskriver samma API. YAML är något mer kompakt och lättläst om du själv vill granska filen och används därför som exempel här. Spara filen på en plats där du enkelt hittar den igen, till exempel i din nedladdningsmapp.

Steg 6 – Starta Claude Code

Öppna Claude Code för Windows. Du kan antingen peka Claude Code mot en projektmapp där du vill skapa applikationen eller låta programmet arbeta i en tom mapp som du skapar för ändamålet.

Steg 7 – Skriv en prompt till Claude Code

Ge Claude Code tillgång till den nedladdade OpenAPI-filen (dra in filen i chatten eller ange sökvägen) och beskriv vad du vill bygga. Ett exempel:

@api.yaml
We are going to create a PHP app using DirSys public API reading
out information carriers from DirSys Security.

Var så konkret som möjligt om språk och typ av applikation (kommandoradsverktyg, webbsida eller skrivbordsapp). Om prompten är tvetydig – till exempel om du nämner två ramverk som inte hör ihop – ber Claude Code om ett förtydligande innan den börjar bygga, i stället för att gissa.

Några andra exempel att utgå från:

// Skrivbordsapp i Python
@api.yaml Build a Python desktop app with a PyQt GUI that lists
information carriers from DirSys Security and lets me store my API key.

// Kommandoradsverktyg
@api.yaml Build a Python CLI script that lists personal data processes
from DirSys Integrity, reading the API key from an environment variable.

Steg 8 – Testa och iterera

Claude Code läser in specifikationen, skriver koden och ber om tillåtelse innan den kör kommandon som installerar paket eller startar applikationen. Testa resultatet och be om justeringar med naturligt språk – fler kolumner, ett filter eller ett annat gränssnitt – precis som i en vanlig konversation.

Exempel: så blev applikationen

Resultatet av den här guiden är en skrivbordsapplikation i Python som Claude Code har byggt utifrån prompten i steg 7.

I det här fallet blev resultatet en applikation med ett grafiskt användargränssnitt i tkinter i stället för ett kommandoradsverktyg. Tkinter ingår i Python, och utöver requests krävs inga extra beroenden för gränssnittet. Huvudvyn listar informationsbärare med sortering, sidstorlek och paginering. Ett dubbelklick på en rad öppnar en detaljvy med frågor, risker och kontrollplaner som hämtas från den endpoint som innehåller detaljer för informationsbäraren.

Huvudvyn – lista med sortering, sidstorlek och paginering.

Detaljvyn – öppnas med ett dubbelklick och visar frågor, risker och kontrollplaner.

Inställningar – API-nyckel, val av miljö och knappen Test connection mot /api/public/v1/me.

Applikationen sparar API-nyckeln lokalt som en JSON-fil i %APPDATA%\DirSysICViewer\config.json, så att du slipper ange den varje gång. Den har också en inbyggd knapp för "Test connection" mot /api/public/v1/me för att verifiera nyckeln innan den sparas – samma mönster som beskrivs under Säkerhet och rekommendationer nedan.

Vad Claude Code faktiskt gör åt dig

  • Läser OpenAPI-specifikationen: vilka endpoints som finns, vilka parametrar de accepterar och hur svaren är uppbyggda.
  • Skriver klientkod som skickar din API-nyckel i HTTP-headern Authorization vid varje anrop.
  • Bygger det gränssnitt eller skript du bad om och kopplar ihop det med API-anropen.
  • Kör och testar koden när det är möjligt och rättar fel som upptäcks under tiden.

Autentisering i korthet

Bra att känna till även om Claude Code sköter detta åt dig: varje anrop till DirSys API måste innehålla API-nyckeln i en Authorization-header med prefixet Bearer.

Authorization: Bearer dfk_...

Ett anrop som listar informationsbärare med paginering ser ut så här:

GET https://api.dirsys.app/api/public/v1/security/information-carriers?page=0&size=25&sort=-createdAt
Authorization: Bearer dfk_...

Svaret innehåller en resultatsida med en data-array med posterna, plus page, size, totalElements och totalPages för att hantera pagineringen. Samma mönster gäller för personuppgiftsbehandlingar i DirSys Integrity.

Felsökning

Här är de vanligaste felen som kan uppstå när du kommer igång.

401 – Missing or invalid API key

Vanligast är att Bearer -prefixet saknas framför nyckeln eller att nyckeln av misstag har kopierats med ett mellanslag eller en radbrytning. Kontrollera även att klienten inte har spärrats.

403 – API key lacks READ scope eller tenant/resurs är inte tillgänglig

Antingen saknar klienten READ-behörighet eller så tillhör resursen ett säkerhetsutrymme (eller en controller för personuppgiftsbehandlingar) som klienten inte har åtkomst till. Det är vanligt om klienten skapades som Restricted. Gå tillbaka till klientens inställningar i Developer Portal och kontrollera Permissions och Access Restrictions.

429 – Rate limit exceeded

Standardgränsen är 100 anrop/minut per klient. Ett program som pollar för ofta eller hämtar många sidor snabbt efter varandra kan nå gränsen. Be Claude Code lägga in en kort fördröjning mellan anrop eller kontakta support@dirsys.com för en högre gräns.

Klienten kan inte skapas eller Developer Portal går inte att nå

Se steg 1. Din roll saknar sannolikt API access (Developer portal). Det är en separat inställning som är oberoende av vilka övriga behörigheter du har i DirSys.

Säkerhet och rekommendationer

  • Lagra aldrig API-nyckeln direkt i källkoden.Be Claude Code lägga nyckeln i en miljövariabel eller en konfigurationsfil som inte checkas in i versionshanteringen. Ange detta uttryckligen i prompten om appen ska delas eller läggas i ett kodarkiv.
  • Använd en egen nyckel per applikation. Då kan du spärra en enskild integration utan att påverka andra.
  • Använd minsta möjliga behörighet. READ räcker för allt som bara ska visa data. Lägg bara till WRITE om appen faktiskt ska ändra något, till exempel uppdatera en kommentar på en kontrollpunkt.
  • Ha en rutin för nyckelrotation. Bestäm i förväg hur ofta nyckeln byts ut och vem som ansvarar för det.

Guiden beskriver flödet i Developer Portal och DirSys Public API v1.0.0 så som de såg ut när guiden skrevs. Exempelapplikationen i avsnittet "Så blev applikationen" är byggd i Python (tkinter), och källkoden finns i kodarkivet dirsys-ic-viewer. Om du i stället vill koppla DirSys API till Power Apps via en anpassad connector kan du läsa den separata guiden "Från OpenAPI till Power App".

SHA256: 26b76129cf4f0ba016a504a958a939cd442d34737aa47cefd36b8fe0d66fe8e5