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:

.. code-block:: json

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

Error responses:

.. code-block:: json

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

HTTP Status Codes
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - 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

Filtering & Search
~~~~~~~~~~~~~~~~~~~

- Filter by field: ``?status=new&city=Mumbai``
- Date range: ``?created_after=2026-01-01&created_before=2026-03-31``
- Search: ``?search=customer+name``
- Ordering: ``?ordering=-created_at``

.. toctree::
   :maxdepth: 1
   :hidden:

   accounts
   leads
   surveys
   installations
   procurement
   finance
   reporting
   notifications
   emergency