Resurser

Resurser är centrala för den webbaserade arkitekturen. Det är resursen man utgår ifrån och det är den som man sedan manipulerar med hjälp av operationer (t.ex. GET och POST).

All information som kan namnges kan vara en resurs och resurser är ett centralt begrepp för REST API:er.

Samlingar

En samling (eng. collection) är en speciell typ av resurs och kan ses som en lista med resurser av samma typ. Resurser beskrivs nästan alltid i en struktur med både samlingar och resurser, men resurser kan existera utanför en samling också. 

Exempel:

/organisationer

En GET request på denna samling ger en lista på alla organisationer.

Ofta delas en samling in i ytterligare samlingar, så kallade nästlade samlingar.

Exempel på undersamling ’hemvist’ under resursen ’2021005489’ i samlingen ’organisationer’:

/organisationer/2021005489/hemvist

Identifierare

Följande regler används gällande identifierare för en resurs:

  • Identifieraren BÖR (RES.01) vara beständig, d.v.s. att vara globalt unik över tid. Med global unik identifierare avses en identifierare, som består över tid och refererar till samma resurs.
  • Primärnycklar eller personligt identifierbar information (personnummer, etc.) BÖR INTE (RES.02) exponeras. Om detta är svårt att uppnå är det troligt att API:et behöver abstraheras ytterligare från den underliggande datakällan. Läs mer om Amundsens Maturity Model
  • När numeriska ID:n används BÖR de INTE (RES.03) vara sekventiella. Om informationen är av känslig karaktär ska den skyddas med behörighetskontroll.
  • En identifierare för en nästlad resurs SKALL (RES.04) vara unik inom sin förälder resurs om den är beroende av sin förälder. 

organisationer/2021005489/hemvist/2345 

Identifieraren för hemvist 2345 är unik inom företag 2021005489 men 2345 är nödvändigtvis inte globalt unikt. Dock är den globalt unik tillsammans med företag 2021005489, dvs'2021005489/hemvistkommun/2345'.

När det kommer till att identifiera resurser så BÖR (RES.05) designen av detta ta höjd för en del olika aspekter: 

  • Säkerhet – beakta den identifikation på resurs som förmedlas via API gällande om den kan anses vara känslig eller onödig att exponera. T.ex. består en identifierare av en räknare så är det enkelt att lista ut nästa resurs. Avstå också från att använda primärnycklar i databasen utåt. 
  • Användandet av logiska nycklar – den logiska nyckeln används i exponering utåt medan relationer döljs i backend. Passar bra när resurserna tillhör en domän, såsom SEK tillhör domänen valutor. 
  • Överväg användande av UUID (eller motsvarande) – likt de två ovanstående punkterna så används databasgenererade id:n för att hantera data i backend, medan den logiska nyckeln döljs genom att skapa en UUID (t.ex. genom MD5 hashning av logisk nyckel). UUID kan såklart också genereras trots att det inte finns en logisk nyckel att använda. 

Genom att tänka på ovanstående aspekter så kan både säkerhet och unikhet hanteras för identifierare av resurser. En identifierare som använder UUID eller liknande kan anses vara globalt unik.  

Namnsättningskonvention för resurser

All information som kan namnges kan vara en resurs. En informationsmängd är en entitet och ska därför namnges med hjälp av substantiv. Verb ska inte användas för att namnge resurser. Låt istället HTTP verben (t.ex. POST, GET, PUT och DELETE) utgöra de metoder eller operationer som används för att manipulera resurserna. 

Följande regler för resurser SKALL (RES.06) följas 

  • resurser namnges som substantiv
  • resurser namnges i pluralform, även om den nu kända träffbilden bara ger ett resultat 
  • resurser följer den namnsättningskonvention som beskrivs för URL:er, det vill säga att resurser anges med gemener, använder endast alfanumeriska tecken och bindestreck för att separera eventuella ord. 

Bra exempel:

/anstallda 
/tjanster

Följande skall inte användas:

/get-anstallda - namnge inte resurser med verb
/bokning - namnge inte resurser i singularis
/TJANSTER - namnge inte resurser i versaler