English

Svenska

English

Svenska

Appearance

Pagination and Queries ​

Most GET endpoints in the Amili API support both individual resource retrieval and paginated list retrieval:

  • Individual Resource: GET /{resource}/{id} - Returns a single resource
  • Paginated List: GET /{resource} - Returns a paginated list of resources

Pagination Response Format ​

When retrieving lists of resources, the API returns a paginated response with the following structure:

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 Fields:

  • _items: Array of resource objects
  • _meta.total: Total number of resources available
  • _meta.max_results: Maximum number of results per page
  • _meta.page: Current page number

Query Parameters ​

Most GET endpoints in the Amili API support query parameters for filtering, sorting, pagination, and field projection. These parameters allow you to customize API responses to retrieve exactly the data you need.

Query parameters are appended to the endpoint URL and can be combined to create powerful queries:

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

Filtering with where ​

The where parameter allows you to filter results using JSON expressions. You can filter on top-level fields and nested fields using dot notation.

Basic Filtering ​

Filter results by matching exact field values:

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()

Nested Field Filtering with Dot Notation ​

Use dot notation to filter on nested object fields. This is particularly useful when filtering on related data structures.

Example: Filter cases by invoice number in nested debt object

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()

Sorting with sort ​

The sort parameter allows you to order results by a specific field. Prefix the field name with - for descending order.

Example: Sort by creation date (newest first)

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()

Pagination Parameters ​

Control the number of results and which page to retrieve:

  • page: Page number (default: 1)
  • max_results: Number of results per page (default: 25, max: 100)

Example: Retrieve second page with 50 results

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()

Field Projection with projection ​

The projection parameter allows you to specify which fields to include or exclude in the response. This helps reduce payload size and improve performance.

Example: Include only specific fields

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()

Combining Query Parameters ​

You can combine multiple query parameters to create complex queries:

Example: Filter, sort, paginate, and project fields

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()

Best Practices ​

  1. URL Encoding: Always properly encode JSON query parameters. In TypeScript, use encodeURIComponent() with JSON.stringify(). In Python, the requests library handles encoding automatically when using the params parameter.

  2. Nested Field Access: Use dot notation consistently for nested fields. Field names in dot notation should match the exact structure of the data model.

  3. Performance: Use projection to limit returned fields and reduce payload size, especially when retrieving large datasets.

  4. Pagination: Always implement pagination for list endpoints to avoid retrieving excessive amounts of data in a single request.

  5. Error Handling: Validate query parameters before sending requests. Invalid JSON in where or projection parameters will result in error responses.