📘 API Documentation Standards

1. URI & Naming Conventions

• All endpoints follow RESTful design and use kebab-case (hyphen-separated).
• API versioning is included in the path.

Format:

/api/v1.2/resource-name/

Examples:

• GET /api/v1.2/fields/
• POST /api/v1.2/stratification-maps/
• GET /api/v1.2/orders/order_id/
• GET /api/v1.2/boundary/detect-boundary/

2. Supported Formats

APIs support multiple output formats depending on the endpoint.

Usage:

• Via HTTP Header: Accept: application/json
• Via Query Parameter: ?format=geojson

3. Pagination, Filtering & Sorting

Pagination

Query Parameters:

• page: Number of page to return (e.g., ?page=10)

Example Request:

GET /api/v1.2/fields/?page=10

Example Response:

{
  "count": 100,
  "next": "/api/v1.2/fields/?page=10",
  "previous": "/api/v1.2/fields/?page=11",
  "results": [...]
}

Filtering

Filtering is supported using query parameters via Django's DjangoFilterBackend.

Examples:

• /api/v1.2/maps/?status=completed
• /api/v1.2/maps/?type=ndvi

ℹ️

Custom filters should be documented individually for each endpoint in the API specification.

❌ 4. Error Schema

All error responses follow a consistent JSON schema format.

Example:

{
  "error": {
    "code": "validation_error",
    "message": "Field 'name' is required.",
    "details": {
      "name": ["This field is required."]
    }
  }
}

5. Rate Limit Headers

If rate limiting is enabled (e.g., via middleware or API gateway), the following headers are returned with each response: