Riktlinjer för utveckling av API:er

Säkerhetsregler

All access till APIer skall vara krypterad (https)
Samtliga klienter till ett API skall autentisera sig, antingen via en API-nyckel (asymmetrisk nyckel – välj denna lösning i första hand) eller via basic authentication (endast i yttersta undantagsfall)
Dela så lite data som möjligt i ditt API – endast data som är relevant för en klient skall delas, inget annat
Ett API skall informationssäkerhetsklassas och dess skyddsnivå (0-4) skall dokumenteras – se Instruktioner för informationssäkerhetsklassning och riskanalys
Begränsa antalet anrop/tidsenhet per API och klient till, efter överenskommelse, rimliga nivåer för att förhindra störningar på grund av DDOS-attacker och liknande
Validera alltid alla in-parametrar i ett API-anrop (schema-validering), för att förhindra SQL-injektion och liknande

Ett API får finnas i två samtidigt supporterade versioner i produktion; den nu gällande versionen (markerat som ACTIVE) samt den senaste versionen innan den (som skall markeras som DEPRECATED)
Anropande system har 6 månader på sig att styra om till ett APIs nya version – efter 6 månader slutar den gamla versionen att supporteras (status RETIRED)
När ett API i status RETIRED inte fått några anrop på 3 månader skall det helt tas bort (status DECOMMISSIONED)
Ett API skall versionshanteras i (minst) två nivåer (exempel: version 1.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 1.0 till 2.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 1.0 till 1.1)
Ett API skall exponera sitt versionsnummer i sin url

APIer skall exponeras som REST APIer och acceptera anrop, samt leverera svar, på JSON-format (Content-Type: application/json)
Använd API-standarder i så stor utsträckning som möjligt (uppfinn inte hjulet i onödan)
- Exempel: SensorThings API (https://en.wikipedia.org/wiki/SensorThings_API) för APIer som hanterar sensor-data
Om API-standard saknas, designa APIet i enlighet med grundprinciperna för REST (https://sv.wikipedia.org/wiki/Representational_State_Transfer)
För öppna APIer skall OpenAPI Specification (https://swagger.io/specification/) särskilt beaktas

Sidansvarig

Per Persson