API & Views

ChargeSol exposes a RESTful API built with Django REST Framework. All endpoints follow consistent conventions.

API Conventions

Base URL

All endpoints are prefixed with /api/v1/.

Authentication

JWT-based authentication using SimpleJWT:

  • POST /api/v1/auth/login/ — obtain access + refresh tokens

  • POST /api/v1/auth/refresh/ — refresh access token

  • Include token in header: Authorization: Bearer <access_token>

  • Access token TTL: 15 minutes

  • Refresh token TTL: 7 days

Pagination

Cursor-based pagination for list endpoints:

  • Default page size: 20

  • Max page size: 100

  • Response includes next and previous cursor URLs

Response Envelope

All responses follow a standard envelope:

{
  "status": "success",
  "data": { },
  "message": "Operation completed"
}

Error responses:

{
  "status": "error",
  "data": null,
  "message": "Validation failed",
  "errors": {
    "field_name": ["Error description"]
  }
}

HTTP Status Codes

Code

Usage

200

Successful GET, PATCH, PUT

201

Successful POST (resource created)

204

Successful DELETE

400

Validation error

401

Authentication required

403

Permission denied (role-based)

404

Resource not found

409

Conflict (e.g., invalid status transition)

429

Rate limit exceeded