REST API Endpoints

NewLoom provides a RESTful API using Django REST Framework. This section documents the available endpoints and their usage.

Authentication

All API endpoints require authentication. The following authentication methods are supported:

• Token Authentication (Authorization: Token <your-token>)

• Session Authentication (for browser-based access)

For details on obtaining tokens and authentication setup, see Authentication.

Common Headers

• Content-Type: application/json

• Accept: application/json

• Authorization: Token <your-token>

Pagination

API responses are paginated by default with the following structure:

{
    "count": 100,
    "next": "http://api.example.org/items/?page=2",
    "previous": null,
    "results": []
}

Configuration:

• Default page size: 10

• Maximum page size: 100

• Page size parameter: ?page_size=20

Sources API

List Sources

Create Source

Streams API

List Streams

Create Stream

News API

List News Articles

Error Responses

The API uses standard HTTP status codes and provides detailed error messages:

400 Bad Request

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "Invalid request",
    "detail": {
        "field_name": [
            "This field is required."
        ]
    }
}

401 Unauthorized

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "Authentication credentials were not provided."
}

404 Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "detail": "Not found."
}

Rate Limiting

API endpoints are rate limited to prevent abuse:

• Authenticated requests: 1000 requests per hour

• Anonymous requests: 100 requests per hour

Rate limit headers are included in responses:

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