Filtrering, paginering och sökparametrar
Rekommendationen är att utföra filtrering med hjälp av frågeparametrar. En tumregel vid design är att först utesluta att parametern som potentiellt ska användas för filtrering inte egentligen borde vara en header parameter samt att informationen inte är känslig (exempelvis lösenord). I slutändan är det viktigaste att de vanligaste användningsfallen ska vara enkla att realisera för användaren och det ska vara svårt att göra fel.
Notis!
Filtrerings och sökparametrar är inte en del utav definitionen av en webbresurs.
Felaktig URL: /annonser/from/20210101/to/20210131
Filtrering
Filtrering ger användaren möjligheter att välja den information som den är intresserad av genom API:et.
Den enklaste modellen är att ange ett attribut som används som filter för en samling av resurser.
Tänk en samling som exempelvis innehåller alla kommuner i Sverige:
/kommuner
Ett sätt att filtrera så att svar enbart innehåller kommuner baserat från ett län:
/kommuner?lan=17
Då det kan vara svårt att veta hur ett län kan anges ska det tydligt framgå vilka potentiella värden som kan anges, i schema, dokumentation eller via en hyperlänk. Ex. https://www.scb.se/hitta-statistik/regional-statistik-och-kartor/regionala-indelningar/lan-och-kommuner/
Exempel
/kommuner?lan=17
/annonser?from=2021-01-01&to=2021-01-31
/bolag?SNI_kod=10
Operator
Likhetstecken (=) är den enda operator som används vid enklare filtrering och (&) används för att separera flera parametrar. Det finns andra sätt att filtrera som erbjuder fler operatorer.
Namnsättningskonvention för sökparametrar
Att filtrera kan realiseras genom uttrycka sig med sökfrågor (eng. query)
Nedan följer några rekommendationer kring detta:
- Parameternamn SKALL (FNS.01) anges med en konsekvent namnkonvention inom ett API, exempelvis antingen snake_case eller camelCase.
- Sökparametrars värden SKALL (FNS.02) vara percent-endcoded (RFC3986) på UTF-8 format.
- Exempelvis skall ‘ ', dvs blanksteg, kodas till '%20’.
- Sökparametrar SKALL (FNS.03) starta med en bokstav.
- Sökparametrar BÖR (FNS.04) använda enbart gemener.
- Sökparametrar BÖR (FNS.05) vara frivilliga.
- Sökparametrar BÖR (FNS.06) använda tecken som är URL-säkra (tecknen A-Z, a-z, 0-9, "-", ".", "_" samt "~", se vidare i RFC 3986).
Exempel:
https://taxonomy.api.jobtechdev.se/v1/taxonomy/specific/concepts/country?preferred_label=South%20america&version=1
Paginering
Avser metoden att dela upp större datamängder till mindre mer hanterbara delar som levereras i varje request.
Paginering rekommenderas användas för att hantera icke-funktionella krav såsom prestanda och upptider, ofta uttrycka i SLA krav.
Parametrar
Vid användande av paginering, SKALL (FNS.07) följande parametrar ingå i request.
Parameter | Beskrivning | Exempel |
---|---|---|
page eller offset | Page är sida i träfflista som konsument vill erhålla Offset är startposition i träfflistan som konsument vill börja hämta ifrån | page=1 (default: 1) offset=0 (default:0) |
limit | Antal sökträffar per sida som konsumenten vill erhålla | limit=20 (default:20) |
Strukturen blir då följande:
/organisationer?page=3&limit=20
/organisationer?offset=60&limit=20
Denna struktur är lätt att förstå och kan användas direkt i ett gränssnitt.
page SKALL (FNS.08) alltid starta med värde 1 och defaultvärde för limit BÖR (FNS.09) vara 20. offset börjar ofta med 0 som startposition, och beräknas med hjälp av limit till efterföljande sökning.
Response
När paginering implementeras, BÖR (FNS.10) man inkludera fält för _meta och _links för att förse konsumenten med information om resultatet, och erbjuda enkel navigation i träffbilden. Dessa fält tar bort klientens behov hantera pagineringen på konsumentsidan, alternativen serveras direkt i svaret.
- _links fältet BÖR (FNS.11) inkludera länkar for self, first, last, next och prev.
- Varje länk SKALL (FNS.12) inkludera alla eventuellt övriga frågeparametrar som skickades i första request.
Ett exempel på svar:
HTTP/1.1 200 OK
Content-Type: application/hal+json
...
{
"_meta": {
"total_records": 98,
"page": 3,
"limit": 20,
"count": 20
} ,
"_links": [
{
"href": "/organisationer?page=3&limit=20",
"rel": "self"
},
{
"href": "/organisationer?page=1&limit=20",
"rel": "first"
},
{
"href": "/organisationer?page=5&limit=20",
"rel": "last"
},
{
"href": "/organisationer?page=2&limit=20",
"rel": "prev"
},
{
"href": "/organisationer?page=4&limit=20",
"rel": "next"
}
],
"organisationslista": ...
}
Givet ovan exempel BÖR (FNS.13) följande struktur appliceras på meta objektet:
Attribut | Typ | Beskrivning |
---|---|---|
totalRecords | Heltal | Totalt antal träffar på aktuella sökparametrar, oaktat sida och antal. |
page | Heltal | Aktuell sida för träffbilden. |
offset | Heltal | Startposition i träfflistan. |
limit | Heltal | Begärd antal resultat per sida. |
count | Heltal | Antal resultat på aktuell sida. |
Utanför träffbilden
Om konsumenten begär en sida som är utanför det giltiga spannet för träffbilden, tex om sidspannet går från 1 till 15 men konsumenten begär ?page=0 eller ?page=99, BÖR (FNS.14) svaret innehålla en tom träffbild med HTTP statuskod 200.
Ett exempel följer:
HTTP/1.1 200 OK
Content-Type: application/hal+json
...
{
"_meta": {
"totalRecords": 98,
"page": 99,
"limit": 20,
"count": 0
},
"_links": [
{
"href": "/organisationer?page=99&limit=20",
"rel": "self"
},
{
"href": "/organisationer?page=1&limit=20",
"rel": "first"
},
{
"href": "/organisationer?page=15&limit=20",
"rel": "last"
}
],
"organisationslista": []
}