Svenska

English

Svenska

English

Appearance

Paginering och frågor ​

De flesta GET endpoints i Amili API stöder både individuell resurshämtning och paginerad listhämtning:

  • Individuell resurs: GET /{resource}/{id} - Returnerar en enda resurs
  • Pagerad lista: GET /{resource} - Returnerar en paginerad lista av resurser

Pagineringsresponse-format ​

När du hämtar listor av resurser returnerar API:et ett paginerat svar med följande struktur:

json
{
  "_items": [
    {
      "_id": "resource_id_1",
      "name": "Resource Name 1"
      // ... other resource fields
    },
    {
      "_id": "resource_id_2",
      "name": "Resource Name 2"
      // ... other resource fields
    }
  ],
  "_meta": {
    "total": 150,
    "max_results": 25,
    "page": 1
  }
}

Response-fält:

  • _items: Array av resursobjekt
  • _meta.total: Totalt antal tillgängliga resurser
  • _meta.max_results: Maximalt antal resultat per sida
  • _meta.page: Nuvarande sidnummer

Query-parametrar ​

De flesta GET endpoints i Amili API stöder query-parametrar för filtrering, sortering, paginering och fältprojektion. Dessa parametrar gör att du kan anpassa API-svar för att hämta exakt de data du behöver.

Query-parametrar läggs till i endpoint-URL:en och kan kombineras för att skapa kraftfulla frågor:

GET /cases?where={"status":"active"}&sort=-_created&page=1&max_results=25

Filtrering med where ​

Parametern where gör att du kan filtrera resultat med JSON-uttryck. Du kan filtrera på toppnivåfält och kapslade fält med punktnotation.

Grundläggande filtrering ​

Filtrera resultat genom att matcha exakta fältvärden:

typescript
const token = await auth.getValidToken()
const query = encodeURIComponent(JSON.stringify({ status: 'active' }))
const response = await axios.get(
  `https://api-sandbox.amili.se/cases?where=${query}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()
query = json.dumps({'status': 'active'})
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={'where': query},
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Filtrering av kapslade fält med punktnotation ​

Använd punktnotation för att filtrera på kapslade objektfält. Detta är särskilt användbart när du filtrerar på relaterade datastrukturer.

Exempel: Filtrera cases efter fakturanummer i kapslat debt-objekt

typescript
const token = await auth.getValidToken()
const query = encodeURIComponent(
  JSON.stringify({ 'debt.invoice_number': '1234567' })
)
const response = await axios.get(
  `https://api-sandbox.amili.se/cases?where=${query}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()
query = json.dumps({'debt.invoice_number': '1234567'})
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={'where': query},
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Sortering med sort ​

Parametern sort gör att du kan ordna resultat efter ett specifikt fält. Prefixa fältnamnet med - för fallande ordning.

Exempel: Sortera efter skapandedatum (nyaste först)

typescript
const token = await auth.getValidToken()
const response = await axios.get(
  'https://api-sandbox.amili.se/cases?sort=-_created',
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
token = auth.get_valid_token()
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={'sort': '-_created'},
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Pagineringsparametrar ​

Styr antalet resultat och vilken sida som ska hämtas:

  • page: Sidnummer (standard: 1)
  • max_results: Antal resultat per sida (standard: 25, max: 100)

Exempel: Hämta andra sidan med 50 resultat

typescript
const token = await auth.getValidToken()
const response = await axios.get(
  'https://api-sandbox.amili.se/cases?page=2&max_results=50',
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
token = auth.get_valid_token()
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={'page': 2, 'max_results': 50},
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Fältprojektion med projection ​

Parametern projection gör att du kan specificera vilka fält som ska inkluderas eller exkluderas i svaret. Detta hjälper till att minska nyttoansvarstorleken och förbättra prestandan.

Exempel: Inkludera endast specifika fält

typescript
const token = await auth.getValidToken()
const projection = encodeURIComponent(
  JSON.stringify({
    _id: 1,
    status: 1,
    'debt.invoice_number': 1,
    'customer.name': 1,
  })
)
const response = await axios.get(
  `https://api-sandbox.amili.se/cases?projection=${projection}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()
projection = json.dumps({
    '_id': 1,
    'status': 1,
    'debt.invoice_number': 1,
    'customer.name': 1,
})
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={'projection': projection},
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Kombinera query-parametrar ​

Du kan kombinera flera query-parametrar för att skapa komplexa frågor:

Exempel: Filtrera, sortera, paginera och projicera fält

typescript
const token = await auth.getValidToken()
const where = encodeURIComponent(
  JSON.stringify({ 'debt.invoice_number': '1234567' })
)
const projection = encodeURIComponent(
  JSON.stringify({
    _id: 1,
    status: 1,
    'debt.invoice_number': 1,
    'customer.name': 1,
  })
)
const response = await axios.get(
  `https://api-sandbox.amili.se/cases?where=${where}&sort=-_created&page=1&max_results=25&projection=${projection}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
import json

token = auth.get_valid_token()
where = json.dumps({'debt.invoice_number': '1234567'})
projection = json.dumps({
    '_id': 1,
    'status': 1,
    'debt.invoice_number': 1,
    'customer.name': 1,
})
response = requests.get(
    'https://api-sandbox.amili.se/cases',
    params={
        'where': where,
        'sort': '-_created',
        'page': 1,
        'max_results': 25,
        'projection': projection,
    },
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

Bästa praxis ​

  1. URL-kodning: Koda alltid JSON query-parametrar korrekt. I TypeScript, använd encodeURIComponent() med JSON.stringify(). I Python hanterar requests-biblioteket kodning automatiskt när du använder params-parametern.

  2. Åtkomst till kapslade fält: Använd punktnotation konsekvent för kapslade fält. Fältnamn i punktnotation bör matcha den exakta strukturen i datamodellen.

  3. Prestanda: Använd projection för att begränsa returnerade fält och minska nyttoansvarstorleken, särskilt när du hämtar stora dataset.

  4. Paginering: Implementera alltid paginering för listendpoints för att undvika att hämta överdrivet stora mängder data i en enda begäran.

  5. Felhantering: Validera query-parametrar innan du skickar begäranden. Ogiltig JSON i where- eller projection-parametrar kommer att resultera i felmeddelanden.