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 elementAPI elementBeskrivningExempel
SchemeprotokollAlla API:er SKALL (UFN.02) exponeras via HTTPS på port 443.https
AuthoritydomännamnDomännamnet där API:ets endpoint exponerasgw.api.bolagsverket.se
Pathapi

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
PathversionAlla API:er BÖR (VER.05) exponera versionen enligt versionshanteringsbeskrivningen i denna standard, se vidare under Versionshantering./v2
PathresursResurser SKALL anges som ett substantiv i pluralform, se vidare under Resurser./organisationer
PathidentifierareEn identifierare till en resurs./2021005489 
Queryparameter

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