👷‍♂️ SweLint är för närvarande under konstruktion. Tabellen nedan ska slutligen innehålla alla riktlinjer från DIGG. Varje riktlinje ska vara märkt med om den är testbar eller inte. Alla testbara riktlinjer ska dessutom ha en länk till ett exempel.

SweLint är det första publicerade lint-verktyget för de nationella svenska Api-riktlinjerna från DIGG.

Det finns några frågetecken och utmaningar kring dessa riktlinjer.

  • Riktlinjerna har primärt publicerats som löpande text utspridet på flera hemsidor. Insprängt i denna löpande text finns specifika regler med unika identiferare (t.ex MOG.02). Det finns inget sätt att lista dessa identifierare eller vissa dem i tabellform. Detta gör dem rätt krångliga att arbeta med. Framför allt om man vill skumma igenom dem utan tidigare erfarenhet. Det finns en pdf och en excel-fil att ladder ner också, excel-filen är något enklare att arbeta med.

  • Att dömma av detta forum-inlägg så verkar det oklart om dessa riktlinjer är versionshanterade på ett korrekt/konsekvent sätt. Riktlinjer skrivna för utvecklare borde med fördel kunna vara skrivna och versionhanterade i t.ex markdown på GitHub eller liknande.

  • Det är oklart om dessa riktlinjer är i aktiv användning av någon.

  • Många av riktlinjerna förefaller rätt subjektiva. Det gör också att de inte lämpar sig särskilt väl för att testas med ett lint-verktyg.

Dessa riktlinjer och SweLint som verktyg är förmodligen primärt intressanta om du är verksam i den svenska myndighets-sfären. Nedan har riktlinjerna sammanställts i tabellform, baserat på ovan nämnda excel-fil. För att se till att riktlinjerna går att spåra för SweLint:s egen räkning så versionshanteras denna på GitHub (potentiellt inte publikt repo föräns SweLint är i färdigt skickt).

Riktlinje Nivå Beskrivning SweLint Status Ytterligare Kommentar
Dokumentation (DOK.*)
DOK.01 BÖR I regel Bör okumentationen och specifikationen för ett API finnas allmänt tillgänglig online.
DOK.02 BÖR Vidare BÖR ett API:s dokumentation och specifikation finnas sökbara via Sveriges dataportal.
DOK.03 SKALL Dokumentationen för ett API SKALL innehålla följande:


• Om API
• Användarvillkor
• Datamodell för representation av resurser
• Krav på autentisering
• Livscykelhantering och versionshantering
• Kontaktuppgifter
DOK.04 SKALL Dokumentationen och i synnerhet specifikationen SKALL ses som ett kontrakt mellan designer och utvecklare samt mellan producent och konsument av API:et.
DOK.05 SKALL Dokumentationen SKALL versionshanteras tillsammans med API:et.
DOK.06 BÖR Dokumentationen BÖR finnas på både svenska och engelska.
DOK.07 BÖR Dokumentationen av ett API BÖR innehålla övergripande information om API:et.
DOK.08 SKALL Ett API:s servicenivå SKALL finnas tydligt beskrivna i dokumentationen.
DOK.09 SKALL Kända problem och begränsningar SKALL finnas tydlig beskrivning dokumentationen.
DOK.10 SKALL Om det är känt SKALL tidpunkt för när API:et tas ur bruk anges i dokumentationen.
DOK.11 SKALL Avsikten och beteendet hos API:et SKALL beskrivas så utförligt och tydligt som möjligt.
DOK.12 SKALL Ett API:s resurser och de möjliga operationer som kan utföras på resursen SKALL beskrivas så utförligt och tydligt som möjligt.
DOK.13 SKALL Förväntade returkoder och felkoder SKALL vara fullständigt dokumenterade.
DOK.14 SKALL Krav på autentisering SKALL anges i dokumentationen.
DOK.15 SKALL I dokumentationen av API:et SKALL exempel på API:ets fråga (en:request) och svar (en:reply) finnas i sin helhet.
DOK.16 SKALL REST API:er SKALL ha en API specifikation som bör kunna generera en datamodell för representation av API:ets resurser.
DOK.17 BÖR API specifikation BÖR dokumenteras med den senaste versionen av OpenAPI Specification. ✅ Example
DOK.18 BÖR API specifikationen BÖR beskrivas med antingen JSON eller YAML.
DOK.19 SKALL Ett API:s resurser och de möjliga operationer som kan utföras på resursen SKALL beskrivas så utförligt och tydligt som möjligt.
DOK.20 SKALL Förväntade returkoder och felkoder SKALL vara fullständigt dokumenterade.
DOK.21 SKALL Krav på autentisering SKALL anges i specifikationen.
DOK.22 SKALL Varje ny major-version av ett API, enligt versionshanteringsavsnittet, SKALL följas av en ny API specifikation.
DOK.23 SKALL API specifikationen SKALL återfinnas under API-roten, det vill säga:{protokoll}://{domännamn}/{API}/{version}/
DOK.24 SKALL Om API specifikationen specificeras med OpenAPI SKALL roten till specifikationen namnges med openapi.yaml eller openapi.json.