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.

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.

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:

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": []
}