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.

Format	Description
GeoJSON	Spatial data (e.g., field boundaries)
Shapefile	GIS-compatible zipped shapefiles
CSV	Tabular data such as reports

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."]
    }
  }
}

Code	Meaning
400	Bad Request (validation, missing params)
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

5. Rate Limit Headers

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

Header	Description
`X-RateLimit-Limit`	Max requests allowed in current window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Time (in seconds) until the limit resets