API Specification
The backend and frontend of PlugZero Analytics talk to each other through a REST API. We use a “Contract-First” approach, which means the API rules are documented before we write the code.
Technical Documentation (drf-spectacular)
Our API documentation is generated automatically from our Django code.
- URL: You can view the live interactive docs at
PLUGINZERO_URL/api/docs/. - Format: We follow the OpenAPI 3.1 standard.
How to use the API
1. Authentication
Most endpoints require you to be logged in. You must include a JWT token in the header of every request.
Authorization: Bearer <your_token_here>2. Standard Responses
200 OK: The request was successful.201 Created: A new thing (like a project) was made.202 Accepted: The server started a long task in the background. You will get atask_idin response.400 Bad Request: You forgot a required field or sent the wrong data type.403 Forbidden: You are logged in, but you don’t have permission to see this data (e.g., it belongs to another team).
Common Endpoints
| Path | Method | Description |
|---|---|---|
/api/accounts/me/ | GET | Returns your user profile and team list. |
/api/projects/ | GET/POST | List projects or create a new one. |
/api/analysis/run/ | POST | Starts a math calculation task. |
/api/surveys/ | GET | List all active surveys for a project. |
Technical Detail: Type Safety
We use the API schema to generate TypeScript types for the frontend.
- Location:
src/types/api.ts - Rule: If you change an API field name in the backend, you must update the schema so the frontend types stay in sync.
Developer Tip: Use the browser’s Network tab to see exactly what JSON data the frontend is sending to the backend. It’s the fastest way to debug API issues.
Last updated on