API-design

• 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/json

    • application/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 )

• 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