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

Regler för livscykelhantering

• 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 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)
• Ett API skall exponera sitt versionsnummer i sin url

Riktlinjer för API-design

• 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