URL Format och namngivning

URL:ers syntax och semantik beskrivs i specifikationen RFC 3986. Specifikationen förenklar utveckling och användning av REST API:er genom att standardisera strukturen och betydelsen av URL:er. Beskrivningen i detta kapitel följer denna standard.

Läs ner om specifikationen RFC 3986

URL komponenter

Strukturen på ett API:s URL ska vara meningsfullt för en konsument. För att öka förståelsen och användbarheten underlättar det om en URL följer en förutbestämd struktur.

En URL för ett API BÖR (UFN.01) följa namnstandarden nedan:

{protokoll}://{domännamn }/{api}/{version}/{resurs}/{identifierare}?{parametrar}

Exempel:

GET https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489?fields=postadress,firmateckning

I vissa fall kan domännamnet vara det samma som API:et och då behövs inte API-delen i URL:en anges. I andra fall, i synnerhet för länkade data, brukar man inte ange versions-delen. I dessa fall krävs att versionshanteringen sköts på annat sätt.

Nedan visas en nedbrytning av hur man konstruera en URL enligt ovan.

URI element	API element	Beskrivning	Exempel
Scheme	protokoll	Alla API:er SKALL (UFN.02) exponeras via HTTPS på port 443.	https
Authority	domännamn	Domännamnet där API:ets endpoint exponeras	gw.api.bolagsverket.se
Path	api	Sökväg inom domänen till API:et. Ofta är sökvägen logiskt indelad i ett affärsområde, verksamhetsområde eller tjänsteområde. (Tänk på att namnsättning ej bör återspegla en föränderlig organisationsstruktur). Ibland består domännamnet av själva API:et då faller denna del bort.	/foretagsinformation
Path	version	Alla API:er BÖR (VER.05) exponera versionen enligt versionshanteringsbeskrivningen i denna standard, se vidare under Versionshantering.	/v2
Path	resurs	Resurser SKALL anges som ett substantiv i pluralform, se vidare under Resurser.	/organisationer
Path	identifierare	En identifierare till en resurs.	/2021005489
Query	parameter	Parametrar i sökfrågor SKALL INTE (UFN.03) användas för att transportera payload eller faktiska data. Ofta används sökfrågefältet för att filtrera, sortera, avgränsa vilka fält som ska visas eller paginera resultatet. Om API:et stödjer begränsning av returnerade fält, komplicerad filtrering, sortering eller paginering BÖR (UFN.04) API:et stödja: fields - specificera eller begränsa vilka fält som ska returneras filter - villkor som begränsar/filtrerar resultatets träffbild vid mer komplicerad filtrering (t.ex. större än). Vid enkel filtrering använd exempelvis ”=” direkt sort - hur resultatet ska sorteras page - specificerar vilken sida som ska returneras i en träffbild Se vidare under Filtrering, paginering och sökparametrar.	?fields=postadress, firmateckning Denna sökfråga kommer att returnera fälten postadress och firmateckning. ?filter=bildat%20gt% 202020-01-01 (alternativt enklare filtrering utan filter: ?bildat %3E2020-01-01 ) Sökträff kommer bara att innehålla objekt som har bildats efter datum 2020-01-01 ?sort=hemvist%20desc Träffbilden kommer att sorteras i fallande ordning på fältet hemvist ?page=2 Returnerar sida 2 i träffbilden

URI maxlängd

En URL BÖR INTE (UFN.05) vara längre än 2048 tecken. Trots att RFC 7231 inte sätter någon gräns tillåter många webbläsare max 2048 tecken därför är det säkrast att längden är max 2048 tecken lång.

URI namnsättningskonvention

En URL skall följa nedan beskrivna namnkonvention

Bokstäver i URL:n SKALL (UFN.06) bestå av enbart gemener
URL:n SKALL (UFN.07) använda tecken som är URL-säkra (tecknen A-Z, a-z, 0-9, "-", ".", "_" samt "~", se vidare i RFC 3986)
Endast bindestreck '-' SKALL (UFN.08) användas för att separera ord för att öka läsbarheten samt förenkla för sökmotorer att indexera varje ord för sig. Blanksteg ' ' och understreck '_' SKALL INTE (UFN.09) användas i URL:er med undantag av parameter-delen.
Understreck '_' SKALL (UFN.10) endast användas för att separera ord i parameternamn.
Understreck '_' SKALL INTE (UFN.11) vara del av bas URL:en.

Se vidare under Filtrering, paginering och sökparametrar rörande namnsättning av sökfrågors parameternamn.

Goda exempel

Lista organisationer

GET https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer

Filtreringsfråga

GET https://gw.api.bolagsverket.se/foretagsinformation/v2/organsiationer?filter=bildat%20gt%202020-01-01

Hämta information om en enskild organisation

GET https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489

Hämta endast enstaka fält för en organisation

GET https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489?fields=postadress,firmateckning

Uppdatera en enstaka organisation

PUT https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489

Undvik följande exempel

Singularis

POST https://gw.api.bolagsverket.se/foretagsinformation/v2/person

Verb i URL

POST https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489/skapa

Filtrering i URL istället för i query strängen

POST https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/2021005489/desc