Regler och riktlinjer för våra API:er

• All access till APIer skall vara krypterad (https)
• Samtliga klienter till ett API skall autentisera sig, antingen via API Key eller Oauth2 - vilken metod bestäms av säkerhetsklass på datat som hanteras (se nedan). 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 Länk till annan webbplats. för bakgrund) - följande säkerhetsregler gäller:
  • Skyddsnivå 0 - ingen skyddsnivå.
    Medför ingen negativ påverkan eller skada på egen eller annan organisation eller dess tillgångar, eller på enskild individ.
    Klientautentisering skall ske via API Key.
  • Skyddsnivå 1 - grundläggande skyddsnivå.
    Medför måttlig negativ påverkan på egen eller annan organisation eller dess tillgångar, eller på enskild individ.
    Klientautentisering skall ske via Oauth2.
    
  • Skyddsnivå 2 - utökad skyddsnivå.
    Medför betydande negativ påverkan på egen eller annan organisation eller dess tillgångar, eller på enskild individ.
    Klientautentisering skall ske via Oauth2.
    
  • Skyddsnivå 3 - hög skyddsnivå.
    Medför allvarlig negativ påverkan på egen eller annan organisation eller dess tillgångar, eller på enskild individ.
    Krav på klientautentisering utreds från fall till fall.
    
  • Skyddsnivå 4 - mycket hög skyddsnivå (enligt säkerhetsskyddslagstiftning). Kan medföra skada på Sveriges säkerhet.
    Krav på klientautentisering utreds från fall till fall.
• 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) - undantag kan tillåtas under utvecklingsintensiva perioder
• Anropande system har 6 månader på sig att styra om till ett APIs nya version – efter maximalt 6 månader, eller tidigare om alla anropande system styrt om mot senaste versionen, slutar den gamla versionen att supporteras (status RETIRED)
• När ett API legat i status RETIRED i 3 månader skall det helt tas bort (status DECOMMISSIONED)
• Ett API skall versionshanteras i två nivåer (exempel: 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

• Designa APIer i enlighet med våra riktlinjer i vår API-Strategi
• Följ i övrigt Diggs REST-API-profil Länk till annan webbplats, öppnas i nytt fönster.

Autentisering sker genom API Key eller OAuth2 beroende på säkerhetsklassning, för mer information om OAuth2, se https://oauth.net/2/ Länk till annan webbplats..

API Gateway kommer att hantera autentisering på två sätt:

1. En statisk accessnyckel för APIer med informationssäkerhetsnivå 0 (Öppna APIer)
2. Accessnyckel med begränsad giltighetstid för övriga APIer

Klientapplikationslogik – statisk accessnyckel

Nedan följer en kort summering av den logik som klienter till Sundsvalls kommuns APIer behöver implementera för att kunna anropa APIer med statiska accessnycklar:

1. Den statiska accessnyckeln fås efter kontakt med ägaren av APIet, distribuerad via en säker digital kanal (krypterad e-post t ex)
2. Denna nyckel skall skickas med i header i anropet till de REST-APIer vi exponerar i API Gateway. Accessnyckeln måste lagras hos klienten (databas, fil etc.)

Exempel (curl)

Consumer Key:dummyAUHGGJ2244
Consumer Secret: dummyD6jjd9887
Base64 encoded Consumer Key: Consumer Secret =
NmQxTmNLaVRJU2JWRW00ascXT3lJTmE5X2RrYTo5R1JkMURnQ0lDc1l1SHJnTUJYZGJqUHlkZ1Fh

Använd accessnyckel (för ett Hello World-API)

Accessnyckeln skall skickas med i header i anropet till APIet.

curl -X GET –header ”Accept: application/json” –header ”apikey: 54f3013afe55022d75e711ec2b3a6ae6” https://api-manager-url/helloWorld/1.0.0/?

{ ”answer”: ”Hello World”}

Klientapplikationslogik – tidsbegränsad accessnyckel

Nedan följer en kort summering av den logik som klienter till Sundsvalls kommuns APIer behöver implementera för att kunna anropa APIer med tidsbegränsade accessnycklar:

1. Klientapplikationen hämtar en accessnyckel genom att anropa API Managers token-API (https://api-manager-url/token). Klienten skall autentisera sig med en API-nyckel (Consumer Key: Consumer Secret) vid anrop mot token-APIet. API-nyckeln skall vara Base64-kodad.
2. Klienten får en accessnyckel i svar på anropet till token-APIet. Denna nyckel skall skickas med i header i anropet till de REST-APIer vi exponerar i API Gateway. Accessnyckeln måste lagras hos klienten, i minnet eller på annat sätt (databas, fil etc.)
3. När en accessnyckel inte längre är giltig kommer klienten att få http 401 i svar på ett API-anrop. När så sker måste klienten hämta en ny nyckel som i steg 1 ovan och göra om sitt API-anrop

Exempel (curl)

Consumer Key:dummyAUHGGJ2244
Consumer Secret: dummyD6jjd9887
Base64 encoded Consumer Key: Consumer Secret =
NmQxTmNLaVRJU2JWRW00ascXT3lJTmE5X2RrYTo5R1JkMURnQ0lDc1l1SHJnTUJYZGJqUHlkZ1Fh

Hämta accessnyckel

Steg ett är att hämta accessnykeln via token-APIet.

curl -k -d ”grant_type=client_credentials” -H ”Authorization: Basic
NmQxTmNLaVRJU2JWRW00ascXT3lJTmE5X2RrYTo5R1JkMURnQ0lDc1l1SHJnTUJYZGJqUHlkZ1Fh ” https://api-manager-url/token

{”access_token”:”54f3013afe55022d75e711ec2b3a6ae6″,”scope”:”am_application_scope default”,”token_type”:”Bearer”,”expires_in”:9223372036854775}

Använd accessnyckel (för ett Hello World-API)

Accessnyckeln som hämtades i steg ett skall skickas med i header i anropet till APIet.

curl -X GET –header ”Accept: application/json” –header ”Authorization: Bearer 54f3013afe55022d75e711ec2b3a6ae6” https://api-manager-url/helloWorld/1.0.0/?

{ ”answer”: ”Hello World”}

När accessnyckeln har gått ut

En accessnyckel har en konfigurerar giltighetstid. När giltighetstiden har gått ut returnerar API Gateway http 401 not authorized. Klienten skall då hämta en ny accessnyckel i enlighet med beskrivningen under ”Hämta accessnyckel” ovan.

curl -X GET –header ”Accept: application/json” –header ”Authorization: Bearer 54f3013afe55022d75e711ec2b3a6ae6” https://api-manager-url/helloWorld/1.0.0/?

http 401

Access failure for API: /helloWorld/1.0.0, version: 1.0.0. Make sure your have given the correct access token

Klientkod – bibliotek

Se https://oauth.net/code/ Länk till annan webbplats.