OS2sofd

- Om OS2sofd: https://www.sofd.io/
- Brugervejledning: https://www.sofd.io/brugervejledning/
- Arkitektur: https://www.sofd.io/arkitektur/
- Implementeringsdrejebøger: https://www.sofd.io/implementation-guides/
- Drejebog: OPUS-kommune: https://www.sofd.io/implementation-guides/opus-loen-integration/
- Drejebog: SD-kommune: https://www.sofd.io/implementation-guides/sd-loen-integration/
- Brugerstyring: https://www.sofd.io/idm/
- Forudsætninger og forberedelse: https://www.sofd.io/idm/prerequisites/
- Processer og hændelser: https://www.sofd.io/idm/processes/
- Personinaktivering: https://www.sofd.io/idm/person-inactivation/
- Konfiguration: https://www.sofd.io/idm/configuration/
- Login og SAML: https://www.sofd.io/login/
- API: https://www.sofd.io/api/
- OData (læsning): https://www.sofd.io/api/odata/
- REST-API: https://www.sofd.io/api/rest/
- Fremtidig API-udvikling: https://www.sofd.io/api/strategi/
- Integrationer: https://www.sofd.io/integrationer/
- On-premise agenter: https://www.sofd.io/agents/
- Brugerkonto Agent: https://www.sofd.io/agents/user-account-agent/
- AD Writeback Agent: https://www.sofd.io/agents/ad-writeback-agent/
- AD Replikator Agent: https://www.sofd.io/agents/ad-replikator/
- AD indlæsningsintegration: https://www.sofd.io/agents/ad-indlaesningsintegration/
- OPUS indlæsningsintegration: https://www.sofd.io/agents/opus-indlaesningsintegration/
- Indlæsning af skoleelever: https://www.sofd.io/agents/skoleelev-indlaesning/
- OS2vikar - Brugerkonto Agent: https://www.sofd.io/agents/os2vikar-agent/
- Download: https://www.sofd.io/downloads/
- Ændringslog: https://www.sofd.io/changelog/
- Support og kontakt: https://www.sofd.io/support/


OS2sofd-fællesskabet har vedtaget en strategi for den fremtidige API-udvikling. Den
etablerer en ny, struktureret API-flade til kundevendte integrationer, erstatter
gradvist det nuværende API, og samler læseadgangen ét sted ved at udfase OData over
tid. Strategien er en ramme: de detaljerede beslutninger træffes løbende.

## Hovedlinjer

1. **Ny `/openapi`-flade.** En ny API-flade etableres ved siden af det nuværende
   API og bliver fremover stedet for kundevendte API-funktioner. Den afgrænses
   indledningsvist til grund-stamdatatyperne (Person, Affiliation, User, OrgUnit) og
   udvides derfra.
2. **Gradvis migrering uden tvang.** Nye kundevendte endpoints bygges på den nye
   flade, og eksisterende endpoints migreres, når de alligevel skal opdateres. Ingen
   tvinges til at migrere på en bestemt dato.
3. **Samlet læseadgang; OData udfases over tid.** Kunder får ét skema at integrere
   mod for både læsning og skrivning. OData fortsætter uændret, indtil dens brugere
   kan flyttes over.
4. **Struktureret versionering.** URL-path-versionering (`/openapi/v1/...`) med en
   konservativ ændringspolitik og lange overgangsperioder, så kunder ikke skal
   migrere oftere end nødvendigt.
5. **Stabil API-kontrakt.** API'et beskrives ved separate kontrakt-objekter, så
   ændringer i OS2sofd's interne datamodel ikke automatisk slår igennem til kundernes
   integrationer.

## Rettighedsmodel

Adgang sker via API-nøgler med tre niveauer af kontrol:

- **Ressourcetyper:** læse-/skriveadgang pr. ressource (fx læs personer, skriv
  organisatoriske enheder).
- **Felter:** en nøgle kan begrænses til bestemte felter (fx adgang til navn, men
  ikke CPR).
- **Rækker:** en nøgle kan begrænses til rækker ejet af en bestemt kilde (fx kun
  rækker ejet af kundens lønsystem).

Modellen gør det muligt at udstille data sikkert til flere typer integrationer, hvor
kunden ønsker fuld kontrol med, hvad en given integration kan se og ændre.

## Forventet gevinst

Flere nuværende og fremtidige ændringsønsker forventes at kunne løses gennem API'et
frem for ved videreudvikling af OS2sofd selv, hvilket giver kommunerne større
fleksibilitet til selv at dække egne behov. Til gengæld skal kommunerne i højere grad
selv bygge eller bestille integrationer mod API'et.

## Afgrænsninger og åbne punkter

- **GraphQL er fravalgt** som alternativ til REST/OpenAPI: forretningsregler ved
  skrivning er svære at udtrykke i GraphQL, og det ville give endnu en parallel
  adgangsvej at vedligeholde. Filtrering på den nye flade sker via almindelige
  query-parametre.
- Endnu ikke fastlagt: plan for migrering af eksisterende kunder, plan for udfasning
  af OData, konkret model for administration og udstedelse af API-nøgler, samt
  audit-logning omkring rettighedsmodellen.