Ett API skall tjäna som ingång till en väl avgränsad funktion och äga sin egen livscykel
APIets namn skall vara på engelska och beskriva vad APIet gör och vilken data som hanteras, inte vilket projekt APIet utvecklas inom eller vilket system det går mot
Exempel på ett tillåtet API-namn; CaseManagement - det framgår tydligt att det är ett API för hantering av ärenden
Exempel på icke tillåtna API-namn; bygglovProjektAPI eller metakatalogAPI
Följ OpenAPI-specifikationen (https://swagger.io/specification/)
Supportera någon av
application/jsonapplication/ld+json
Producera typade APIer
Schemat skall vara på engelska
Dela så lite data som möjligt i ditt API – endast data som är relevant för en klient skall delas, inget annat
Validera alltid alla in-parametrar i ett API-anrop (schema-validering), för att förhindra SQL-injektion och liknande
Vanligt förekommande parameter-namn skall specificeras på OpenAPI namnsättning samt återanvändas i samtliga APIer
Det är inte tillåtet att använda personnummer som parameter i våra APIer förutom i absoluta undantagsfall - använd personId i stället (se OpenAPI namnsättning )
Ett API skall exponeras i följande varianter:
Sandbox - en mockad version som returnerar statiska svar (som inte exekverar verksamhetslogik)
Test - en testversion som exekverar verksamhetslogik i testmiljö
Produktion - skarp version som exekverar verksamhetslogik i produktionsmiljöer
Ett API skall versionshanteras i två nivåer (exempel: v1.0)
En API-förändring som bryter kontraktet (som gör att APIet inte är bakåtkompatibelt) skall resultera i att man stegar upp huvudversionen (från till exempel v1.0 till v2.0)
En API-förändring som endast lägger till nya resurser eller parametrar till ett API (som gör att APIet är bakåtkompatibelt) skall resultera i att man stegar upp inom huvudversionen (från till exempel v1.0 till v1.1)
APIer skall dokumenteras på API-katalog APIer skall dokumenteras på API-katalog
APIer skall exponera en /api-docs (se mer på https://dev.dataportal.se/sv/rest-api--profil/krav-pa-apier/ )
Resursen /api-docs skall vara möjligt att anropa utan nycklar
Se även Livscykelhantering av APIer