Gjenfinne gode designprinsipper for API-utvikling med LLM-støtte

Prinsipper for utvikling av gode integrasjoner mellom fagsystemer har vært kjent i flere tiår i industrien. Likevel finner vi stadig API’er som er tydelig langt unna denne standarden. Denne presentasjonen deler innsikt fra et prosjekt om utviklingen av integrasjon mellom to komplekse systemer i fagforeningsdomenet. Det vil vise måten vi har brukt LLM-verktøy på for å få sparring og tilbakemelding på kvaliteten på et offentlig API under utvikling sett fra både produsentens og konsumentens perspektiv

Transcript

1. mufrid We are what we repeatedly do Excellence is not an act, but a habit Aristoteles
2. mufrid Det vi alle «gjentatte ganger gjør»…. ….mens vi utvikler digitale produkter og tjenester
3. mufrid ….er å ta beslutninger
4. mufrid Beslutninger om…. • Om organisasjoner vi er en del av • Om produkter vi utvikler • Om det vi tror vil oppfylle behovene til mennesker som vil bruke det vi lager
5. mufrid Erfaringsbasert påstand:
6. mufrid Fremragende prestasjoner er ofte et resultat av bevisste beslutninger «Excellence»
7. Gjenfinne gode designprinsipper for API-utvikling med LLM-støtte ITForum1.0 2026 Mufrid Krilic Domain-Driven Design Coach CoWork
8. mufrid Ta flere bevisste beslutninger ….med eller uten AI
9. Beslutningsprosess i produktutviklingen Noe forenklet….
10. mufrid Først…. • Må vi levere noe! • Tiden er essensiell • Time-to-Market • Vi har en hypotese som må valideres
11. mufrid Så…. • Oppnår vi suksess med første løsningen • Kunder vil ha mer!
12. mufrid Deretter…. • Følger vi ofte opp med å utvide første løsningen • Essensiell beslutning!
13. mufrid Det vi skal gjennom i dag • Del 1: En historie for å sette kontekst for teknisk diskusjon • Del 2: Bruk av AI til å hjelpe oss med å ta bevisste beslutninger
14. Del 1: Historiefortelling Om en tilsynelatende enkel og essensiell beslutning
15. mufrid To virksomheter • Forsikringsselskap og forsikringsagent «En forsikringsagent selger forsikring på vegne av et eller flere forsikringsselskap, og er forsikringsselskapets representant overfor kunden.» Definisjon fra SNL
16. mufrid Avtale • Agenten kan selge enkelte forsikringsprodukter • Agenten kan lagre data om poliser, forsikringstagere, medforsikrede • Forsikringsselskapet selger «mest komplekse» produkter • Forsikringsselskapet står ansvarlig for skadeoppgjør
17. Use-case: Kjøp av forsikringer
18. mufrid
19. mufrid
20. mufrid Lite integrasjon under kjøp av produkter • Ingen direkte utveksling av data • Kun for analytiske formål
21. Use-case: Oversikt over alle forsikringsavtaler
22. mufrid
23. mufrid
24. mufrid API for å hente alle forsikringsavtaler /api/customer-policies : Policy[] { customerId: string; date: Date } • Hent alle forsikringsavtaler for gitt kunde på angitt dato • Eks. dagens dato
25. mufrid Alle lager modeller…. Modell er en abstraksjon av virkeligheten der de mest relevante elementene er ivaretatt • Hvor eksplisitt er modellen? • Bevisst valg av det som er mest relevant
26. mufrid API er en modell! • Representerer en oppfatning av konsumentens behov • Forsikringstager har behov å vite: «Hva dekker forsikringene mine?»
27. mufrid API er en modell! • Eksempel: Livsforsikring • Policy • StartDate: Date • StopDate: Date • CoverageAsNumberOfG: Integer • Beneficiary: Beneficiary[] • { name, ssn, share }
28. Use-case: Skadeoppgjør
29. mufrid
30. mufrid
31. mufrid Behov! • Hente historisk forløp over alle forsikringsavtaler • Kjøp av produkter • Oppsigelser av avtaler • Økning eller reduksjon av dekning • …..
32. mufrid Beslutning! • Utvide eksisterende API • Hente historikk på samme måte som vi henter oversikt over alle avtaler per dato
33. mufrid Hente forsikringsavtaler *og* historikk /api/customer-policies : Policy[] { customerId: string; date: Date } • Hvis date=<en spesialverdi> // eks. 01.01.1800 ➢ Hent produkthistorikk ➢ Ellers hent forsikringsavtaler på angitt dato
34. mufrid Naturlig beslutning på mange måter • Mer generell modell tilpasset flerfoldige brukerbehov • Minimerer kostnader ved modellendring • På den andre siden….
35. mufrid Vi forener ulike behov i samme løsning Behov: Melde skade Behov: Hvilke forsikringer har jeg?
36. mufrid Vi forener ulike behov i samme løsning Behov: Melde skade Behov: Hvilke forsikringer har jeg? Samme “bruker” Ulike behov
37. mufrid Beslutningen: Generell modell tilpasset flerfoldige brukerbehov Kostnadseffektiv • Minimerer kostnader ved modellendring Kompleksitets-drivende • Ingen brukere får en modell som er tilpasset sine behov • Friksjon mellom brukergrensesnitt og indre modellen • Utydelig dataeierskap
38. mufrid Beslutning! • Utvide eksisterende API • Var dette en bevisst beslutning?
39. Del 2: Bevisste beslutninger Kan AI hjelpe oss?
40. mufrid Rådsprosess! • Før du tar en beslutning…. • Be om råd fra de som blir påvirket! • Be om råd fra de som er eksperter! • Slik at du kan ta en bevisst beslutning
41. mufrid Hvilke beslutninger krever rådsprosess? • Beslutninger som påvirker andre • Endring av API-modell er en slik beslutning • Påvirker de som allerede bruker API’et
42. mufrid Rådsprosess i vår historie • Be om råd fra de som blir påvirket ➢ Snakk med dagens API konsumenter • Be om råd fra de som er eksperter ➢ Her kommer LLM inn i bildet!
43. Hvilke råd fikk vi? ChatGPT om prinsipper for API-design
44. mufrid Hente forsikringsavtaler *og* historikk /api/customer-policies : Policy[] { customerId : string; date: Date } • Hvis date=<en spesialverdi> ➢ Hent produkthistorikk ➢ Ellers hent gyldige forsikringsavtaler på angitt dato
45. mufrid Prinsipp: Eksplisitt kontrakt • Når man går for felles request-body, blir det fort "implisitt prioritet" mellom feltene, og det bryter prinsippet om eksplisitt kontrakt
46. mufrid Prinsipp: Selv-dokumenterende API • Da er det ikke lenger "self-describing API", fordi klienten ikke kan se av URL eller verb hva som faktisk styrer oppslaget.
47. mufrid Prinsipp: Unngå implisitt logikk • Du får altså et skjult forretningsreglement (f.eks. «date=1800 trumfer alt"), som må dokumenteres og håndheves i validering.
48. mufrid Gode designprinsipper for API-utvikling • Eksplisitte kontrakter • Unngå implisitt logikk • Selv-dokumenterende API
49. mufrid
50. mufrid Hente kun avtalehistorikk /api/claims/product-history/by-customer : History[] • Eksplisitt uten skjulte tolkninger • Egen målgruppe • oppgjørsbehandler som vurderer skademelding
51. Eksplisitte kontrakter Kan vi få hjelp til å konkretisere det?
52. mufrid Vi startet med eksempler…. • Prompt: • kan du lage JSON struktur for produktet Livsforsikring med følgende egenskaper: • LifeInsurance: CustomerId, PurchaseDate, Beneficiary, CoverageAsNumberOfG • Så gjentar vi det for alle andre produkter
53. mufrid ….og endte opp med formell kontrakt! • På et tidspunkt foreslår ChatGPT: • Vil du at jeg også visualiserer løsningen i diagram eller gir OpenAPI-spec for denne strukturen?
54. mufrid Open API «The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”
55. mufrid Open API - spec
56. mufrid Gode designprinsipper for API-utvikling • Eksplisitte, formelle kontrakter • Unngå implisitt logikk • Selv-dokumenterende API
57. Modellering med AI Vurdere flere løsningsalternativer/modeller
59. mufrid Se problemet fra flere perspektiver • Flere perspektiver = flere modeller • Vi har derimot en tendens til å gå for den første løsningen vi ser….
60. mufrid Modellering av API-respons • Prompt: • det kan være en kunde har opphold i f.eks. livsforsikring, f.eks. gyldig fra 2005 til 2010 og deretter 3 års opphold og deretter ha aktiv livsforsikring fra 2013
61. mufrid Flere løsningsalternativer foreslått • ChatGPT: • dette er et viktig scenario i forsikring: opphold/gjenopptakelse • For slike tilfeller trenger du å modellere at produktet i seg selv har flere “perioder” med dekning. • Her har du to hovedmåter å strukturere det på: • Løsning 1 – Egen liste over perioder i produktet • Løsning 2 – Ett produkt per periode
62. mufrid Med vurdering av hvert alternativ • ChatGPT: • Hva anbefales? • Hvis du trenger å vite at det i prinsippet er samme forsikring som har blitt gjenopptatt (med historikk samlet), anbefaler jeg Løsning 1 med coveragePeriods. • Hvis du heller vil at hver periode skal stå som en “ny” kontrakt (ofte juridisk enklere), bruk Løsning 2.
63. mufrid Enkelt å diskutere flere modeller • Prompt er orientert rundt scenarier og eksempler • Test-drevet modellering • AI gir oss flere løsninger å vurdere • Eks. Hintet om juridisk perspektiv
64. mufrid Gode designprinsipper for API-utvikling • Eksplisitte, formelle kontrakter • Unngå implisitt logikk • Selv-dokumenterende API • Vurder flere domene-orienterte modeller ut fra ulike perspektiver
65. Oppsummering
66. mufrid Lettere å ta bevisste beslutninger • Gode designprinsipper er tilgjengelige der ute • Tydeligvis ligger i treningsdata til LLM-modeller • Med AI-støtte er det nå lettere, og tar mindre tid, å ta noen avveininger før man tar et designvalg
67. Det vi skulle frem til….
68. mufrid We are what we repeatedly do Excellence is not an act, but a habit Aristoteles
69. mufrid Spole 2300 år frem i tid til et annet sitat….
70. mufrid Excellence is a way of life It’s not just: I show up on Monday and be excellent Kobe Bryant, amerikansk basketballstjerne
71. mufrid Det du derimot kan gjøre er…. På mandag….
72. mufrid …. å ta flere bevisste beslutninger Med eller uten AI-hjelp
73. Takk for meg! • Ta gjerne kontakt! • www.linkedin.com/in/mufrid/ • mufrid@cowork.no Foredraget er en del av kurset: «Domenedrevet produktorganisering» www.cowork.no/kurs/domain-driven-design
75. mufrid Bilder • Vecteezy.com • https://unsplash.com/@onne • https://unsplash.com/@jameskrudop • https://unsplash.com/@loganvoss • https://unsplash.com/@sloppyperfectionist • Keith Allison - Flickr: Kobe Bryant, CC BY-SA 2.0