Sivutus

Fenerum API:n listapäätepisteet käyttävät sivupohjaista sivutusta, jotta suurten aineistojen hakeminen on tehokasta. Oletusarvoisesti jokaisella sivulla on 20 kohdetta.

Sivutuksen parametrit

Kaikki listapäätepisteet tukevat seuraavia kyselyparametreja:

page - Haettava sivunumero (oletus: 1)
page_size - Tulosten määrä sivua kohden (oletus: 20, enintään: 100)

Vastauksen muoto

Sivutetut vastaukset sisältävät seuraavat kentät:

Kenttä	Tyyppi	Kuvaus
`count`	integer	Kokonaismäärä saatavilla olevia kohteita (kaikilla sivuilla)
`next`	string (url), nullable	URL seuraavan sivun hakemiseen
`previous`	string (url), nullable	URL edellisen sivun hakemiseen
`results`	array	Tämän sivun objektien array

Esimerkkipyyntö

GET /api/v1/accounts/?page=2&page_size=50

Esimerkkivastaus

{
  "count": 247,
  "next": "https://app.fenerum.com/api/v1/accounts/?page=3&page_size=50",
  "previous": "https://app.fenerum.com/api/v1/accounts/?page=1&page_size=50",
  "results": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "code": "CUST001",
      "name": "Example Customer"
    }
    // ... more results
  ]
}

Sivujen läpikäynti

Hae kaikki kohteet seuraamalla next-URL-osoitetta, kunnes sen arvo on null:

url = '/api/v1/accounts/'
all_accounts = []

while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    all_accounts.extend(data['results'])
    url = data['next']

Suodatus

Monet listapäätepisteet tukevat suodatusta tulosten rajaamiseksi. Suodattimet annetaan kyselyparametreina.

Perussuodatus

Suodata tietyn kentän arvon perusteella:

GET /api/v1/invoices/?account=CUST001

Vertailusuodattimet

Käytä päätteitä edistyneeseen suodatukseen:

Pääte	Merkitys	Esimerkki
`__lt`	Pienempi kuin	`amount__lt=100`
`__lte`	Pienempi tai yhtä suuri kuin	`created_date__lte=2025-12-31`
`__gt`	Suurempi kuin	`amount__gt=50`
`__gte`	Suurempi tai yhtä suuri kuin	`created_date__gte=2025-01-01`

Esimerkki: aikaväli

Hae laskut, jotka on luotu joulukuussa 2025:

GET /api/v1/invoices/?created_date__gte=2025-12-01&created_date__lt=2026-01-01

Suodatuksen ja sivutuksen yhdistäminen

Voit yhdistää suodatuksen ja sivutuksen:

GET /api/v1/invoices/?account=CUST001&page=2&page_size=50

Vastauksen count-kenttä näyttää suodatettujen tulosten kokonaismäärän, ja next/previous-URL-osoitteet säilyttävät suodattimesi.

Parhaat käytännöt

Käytä tarpeisiisi sopivia page_size-arvoja (pienempiä käyttöliittymää varten, suurempia datan vientiin)
Tarkista aina next-kenttä selvittääksesi, onko lisää sivuja
Käytä suodattimia tulosten määrän pienentämiseksi ennen sivutusta
Välimuistita tulokset mahdollisuuksien mukaan API-kutsujen määrän vähentämiseksi
Tarkista päätepisteen dokumentaatiosta käytettävissä olevat suodattimet