API Documentation¶

Aura Art provides a REST API for programmatic access to your data.

API Overview¶

The API is built using Django REST Framework and provides:

Full CRUD operations for all models
Filtering and searching capabilities
Pagination support
Authentication and permissions
Serialized data in JSON format

Base URL¶

All API endpoints are prefixed with /api/:

Production: https://aura-app.org/api/

Development: http://localhost:8000/api/

Authentication¶

API Key Authentication¶

The API supports API key authentication:

curl -H "Authorization: Api-Key your-api-key" https://aura-app.org/api/artworks/

Session Authentication¶

For web applications, session authentication is supported:

curl -H "Cookie: sessionid=your-session-id" https://aura-app.org/api/artworks/

Endpoints¶

Artworks API¶

List Artworks¶

GET /api/artworks/

Response:

{
    "count": 150,
    "next": "https://your-domain.com/api/artworks/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "title": "Mona Lisa",
            "artist": {
                "id": 1,
                "name": "Leonardo da Vinci"
            },
            "year": 1503,
            "medium": "Oil on canvas",
            "dimensions": "77 x 53 cm",
            "created_at": "2025-01-01T00:00:00Z",
            "updated_at": "2025-01-01T00:00:00Z"
        }
    ]
}

Get Artwork¶

GET /api/artworks/{id}/

Create Artwork¶

POST /api/artworks/

Request body:

{
    "title": "New Artwork",
    "artist": 1,
    "year": 2025,
    "medium": "Oil on canvas",
    "dimensions": "50 x 40 cm"
}

Update Artwork¶

PUT /api/artworks/{id}/

Delete Artwork¶

DELETE /api/artworks/{id}/

Artists API¶

List Artists¶

GET /api/artists/

Get Artist¶

GET /api/artists/{id}/

Create Artist¶

POST /api/artists/

Update Artist¶

PUT /api/artists/{id}/

Delete Artist¶

DELETE /api/artists/{id}/

Collections API¶

List Collections¶

GET /api/collections/

Get Collection¶

GET /api/collections/{id}/

Create Collection¶

POST /api/collections/

Update Collection¶

PUT /api/collections/{id}/

Delete Collection¶

DELETE /api/collections/{id}/

Exhibitions API¶

List Exhibitions¶

GET /api/exhibitions/

Get Exhibition¶

GET /api/exhibitions/{id}/

Create Exhibition¶

POST /api/exhibitions/

Update Exhibition¶

PUT /api/exhibitions/{id}/

Delete Exhibition¶

DELETE /api/exhibitions/{id}/

Contacts API¶

List Contacts¶

GET /api/contacts/

Get Contact¶

GET /api/contacts/{id}/

Create Contact¶

POST /api/contacts/

Update Contact¶

PUT /api/contacts/{id}/

Delete Contact¶

DELETE /api/contacts/{id}/

Notes API¶

List Notes¶

GET /api/notes/

Get Note¶

GET /api/notes/{id}/

Create Note¶

POST /api/notes/

Update Note¶

PUT /api/notes/{id}/

Delete Note¶

DELETE /api/notes/{id}/

Filtering and Search¶

Query Parameters¶

All list endpoints support the following query parameters:

search: Search across relevant fields
ordering: Sort results by field name
page: Page number for pagination
page_size: Number of items per page

Field-Specific Filters¶

Each endpoint supports field-specific filters:

artist__name: Filter by artist name
year__gte: Filter by year greater than or equal
year__lte: Filter by year less than or equal
medium: Filter by medium
created_at__date: Filter by creation date

Example Filtering¶

# Search for artworks by Leonardo da Vinci
curl "https://your-domain.com/api/artworks/?artist__name=Leonardo"

# Get artworks from 2020 onwards
curl "https://your-domain.com/api/artworks/?year__gte=2020"

# Search for oil paintings
curl "https://your-domain.com/api/artworks/?search=oil"

Error Handling¶

Error Responses¶

The API returns appropriate HTTP status codes:

200 OK: Successful request
201 Created: Resource created successfully
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Permission denied
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error Format¶

Error responses include detailed information:

{
    "error": "Validation failed",
    "details": {
        "title": ["This field is required."],
        "year": ["Enter a valid year."]
    }
}

Rate Limiting¶

API Limits¶

The API implements rate limiting to ensure fair usage:

Authenticated users: 1000 requests per hour
Anonymous users: 100 requests per hour

Rate Limit Headers¶

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200