REST API Guide¶

AMSDAL Server automatically generates a REST API for all your models and transactions. This guide covers the available endpoints, query parameters, and usage patterns.

Endpoints Overview¶

Objects (CRUD)¶

Method	Endpoint	Description
GET	`/api/objects/`	List objects (requires `class_name` parameter)
GET	`/api/objects/{address}/`	Get a single object by address
POST	`/api/objects/`	Create an object
PUT	`/api/objects/{address}/`	Full update of an object
PATCH	`/api/objects/{address}/`	Partial update of an object
DELETE	`/api/objects/{address}/`	Delete an object

Bulk Operations¶

Method	Endpoint	Description
POST	`/api/objects/bulk-create/`	Create multiple objects
PUT	`/api/objects/bulk-update/`	Full update of multiple objects
PATCH	`/api/objects/bulk-update/`	Partial update of multiple objects
POST	`/api/objects/bulk-delete/`	Delete multiple objects

Classes¶

Method	Endpoint	Description
GET	`/api/classes/`	List all model classes with metadata
GET	`/api/classes/{class_name}/`	Get detail info for a class

Transactions¶

Method	Endpoint	Description
GET	`/api/transactions/`	List all transactions
GET	`/api/transactions/{transaction_name}/`	Get transaction details
POST	`/api/transactions/{transaction_name}/`	Execute a transaction

Files¶

Method	Endpoint	Description
GET	`/api/objects/file-download/{object_id}/`	Download a file

Filtering¶

Filter objects using query parameters with the format:

?filter[field__operator]=value

If no operator is specified, eq (equality) is assumed.

Operators¶

Operator	Description	Example
`eq`	Equal (default)	`?filter[status]=active`
`neq`	Not equal	`?filter[status__neq]=archived`
`gt`	Greater than	`?filter[age__gt]=18`
`gte`	Greater than or equal	`?filter[age__gte]=18`
`lt`	Less than	`?filter[price__lt]=100`
`lte`	Less than or equal	`?filter[price__lte]=100`
`contains`	Case-sensitive substring	`?filter[name__contains]=john`
`icontains`	Case-insensitive substring	`?filter[name__icontains]=john`
`startswith`	Starts with	`?filter[email__startswith]=admin`
`istartswith`	Starts with (case-insensitive)	`?filter[email__istartswith]=admin`
`endswith`	Ends with	`?filter[email__endswith]=.com`
`iendswith`	Ends with (case-insensitive)	`?filter[email__iendswith]=.COM`

Examples¶

GET /api/objects/?class_name=Person&filter[first_name]=John&filter[age__gte]=18
GET /api/objects/?class_name=Post&filter[title__icontains]=python

Filters on related fields use double-underscore notation for the relationship:

GET /api/objects/?class_name=Employee&filter[company__name]=Acme

Field Selection¶

Request only specific fields using the fields parameter:

?fields[ClassName]=field1,field2

You can also control which metadata fields are returned:

GET /api/objects/?class_name=Person&fields[Person]=first_name,email&fields[Metadata]=version_id

Pagination¶

Parameter	Type	Default	Description
`page`	`int`	`1`	Page number (1-indexed)
`page_size`	`int`	—	Number of items per page

The response includes a total field with the total count of matching records:

GET /api/objects/?class_name=Person&page=1&page_size=10

{
    "columns": [...],
    "rows": [...],
    "total": 156
}

Ordering¶

Sort results using the ordering parameter:

?ordering=[field_name]       # ascending
?ordering=[-field_name]      # descending
?ordering=[field1,-field2]   # multiple fields

Example:

GET /api/objects/?class_name=Post&ordering=[-updated_at]
GET /api/objects/?class_name=Person&ordering=[last_name,first_name]

Bulk Operations¶

Bulk Create¶

POST /api/objects/bulk-create/?class_name=Person
Content-Type: application/json

[
    {"first_name": "John", "last_name": "Doe", "email": "john@example.com"},
    {"first_name": "Jane", "last_name": "Smith", "email": "jane@example.com"}
]

Returns 201 Created with the created objects.

Bulk Update¶

PUT /api/objects/bulk-update/
Content-Type: application/json

[
    {"address": "Person:abc-123", "data": {"first_name": "Updated"}},
    {"address": "Person:def-456", "data": {"email": "new@example.com"}}
]

For partial updates, use PATCH instead of PUT.

Bulk Delete¶

POST /api/objects/bulk-delete/
Content-Type: application/json

[
    {"address": "Person:abc-123"},
    {"address": "Person:def-456"}
]

Returns 204 No Content on success.

Validation¶

Validate object data without saving:

POST /api/objects/{address}/validate/?class_name=Person
Content-Type: application/json

{"first_name": "John", "email": "not-an-email"}

Returns 204 No Content if valid, or error details if validation fails.

File Download¶

Download files with optional image resizing:

GET /api/objects/file-download/{object_id}/

Parameter	Type	Description
`width`	`int`	Target image width in pixels
`height`	`int`	Target image height in pixels
`version_id`	`str`	Specific version (defaults to latest)
`disposition_type`	`str`	`attachment` (default) or `inline`

Examples:

# Download as attachment
GET /api/objects/file-download/file-123/

# Inline display (e.g. in browser)
GET /api/objects/file-download/file-123/?disposition_type=inline

# Resize image to 800x600
GET /api/objects/file-download/file-123/?width=800&height=600

The endpoint supports ETag caching for optimal performance.

Additional Query Parameters¶

The object list and detail endpoints accept these additional parameters:

Parameter	Type	Default	Description
`include_metadata`	`bool`	`true`	Include object metadata in response
`include_subclasses`	`bool`	`false`	Include subclass objects in list
`load_references`	`bool`	`false`	Eagerly load referenced objects
`all_versions`	`bool`	`false`	Include all versions of objects
`decrypt_pii`	`bool`	`false`	Decrypt PII-encrypted fields
`select_related`	`str`	—	Comma-separated related fields to fetch

Example:

GET /api/objects/?class_name=Post&load_references=true&select_related=author,category