API Reference¶

This section provides detailed reference documentation for all Farm API endpoints.

Overview¶

Farm exposes a REST API for managing the portal. All endpoints are prefixed with /api.

Base URL¶

http://localhost:3000/api

Interactive Documentation¶

Farm provides an interactive API documentation interface using Swagger UI. This allows you to explore endpoints, view request/response schemas, and test API calls directly from your browser.

Swagger UI Endpoint: http://localhost:3000/api/docs

Access requires HTTP Basic Auth credentials. The defaults for local development are farm / farm. Set SWAGGER_USER and SWAGGER_PASSWORD environment variables to change them in production.

Authentication¶

All endpoints are protected with JWT-based authentication. Include a Bearer token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Mutation endpoints (POST, PATCH, DELETE) require the admin role.

Available APIs¶

Response Format¶

All responses are JSON formatted. Successful responses include the requested data, while error responses follow a standard format:

{
  "statusCode": 404,
  "timestamp": "2025-01-01T00:00:00.000Z",
  "path": "/api/v1/catalog/components/abc",
  "message": "Component with ID \"abc\" not found"
}

Rate Limiting¶

Rate limiting is enforced globally via the @nestjs/throttler module. Authentication endpoints have stricter per-endpoint limits:

When the rate limit is exceeded, the API returns 429 Too Many Requests.

Versioning¶

The API uses URI-based versioning. All resource endpoints are prefixed with /api/v1/. Infrastructure endpoints (/api/health, /api/metrics, /api/docs) remain version-neutral and do not include a version prefix.