Initial project

docs/API.md

@@ -0,0 +1,192 @@
+# Survey Studio API Guide
+
+Survey Studio is a Django service for creating surveys in admin and collecting
+public responses through JSON endpoints.
+
+## Local Setup
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver
+```
+
+Open:
+
+- Welcome page: `http://127.0.0.1:8000/`
+- Documentation page: `http://127.0.0.1:8000/docs/`
+- Admin panel: `http://127.0.0.1:8000/admin/`
+- Survey API: `http://127.0.0.1:8000/api/surveys/`
+
+## Survey Workflow
+
+1. Sign in to Django admin.
+2. Create a survey.
+3. Add questions inline.
+4. Add choices to single-choice and multiple-choice questions.
+5. Publish the survey.
+6. Fetch the survey schema from the API.
+7. Submit public responses to the response endpoint.
+
+## Question Types
+
+- `short_text`
+- `long_text`
+- `single_choice`
+- `multiple_choice`
+- `rating`
+- `yes_no`
+
+## Endpoints
+
+### List published surveys
+
+```http
+GET /api/surveys/
+```
+
+Example response:
+
+```json
+{
+  "results": [
+    {
+      "id": 1,
+      "title": "Customer Feedback",
+      "slug": "customer-feedback",
+      "description": "Monthly product feedback",
+      "thank_you_message": "Thanks for your response.",
+      "starts_at": null,
+      "ends_at": null,
+      "url": "http://127.0.0.1:8000/api/surveys/customer-feedback/",
+      "response_url": "http://127.0.0.1:8000/api/surveys/customer-feedback/responses/"
+    }
+  ]
+}
+```
+
+### Read a survey schema
+
+```http
+GET /api/surveys/customer-feedback/
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "title": "Customer Feedback",
+  "slug": "customer-feedback",
+  "description": "Monthly product feedback",
+  "thank_you_message": "Thanks for your response.",
+  "starts_at": null,
+  "ends_at": null,
+  "url": "http://127.0.0.1:8000/api/surveys/customer-feedback/",
+  "response_url": "http://127.0.0.1:8000/api/surveys/customer-feedback/responses/",
+  "questions": [
+    {
+      "id": 10,
+      "slug": "experience",
+      "prompt": "How was your experience?",
+      "help_text": "",
+      "type": "single_choice",
+      "required": true,
+      "position": 1,
+      "choices": [
+        {
+          "id": 100,
+          "label": "Good",
+          "value": "good",
+          "position": 1
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Submit a response
+
+```http
+POST /api/surveys/customer-feedback/responses/
+Content-Type: application/json
+```
+
+```json
+{
+  "respondent_email": "person@example.com",
+  "metadata": {
+    "source": "website"
+  },
+  "answers": [
+    {
+      "question": "name",
+      "value": "Alex"
+    },
+    {
+      "question": "experience",
+      "choice": "good"
+    }
+  ]
+}
+```
+
+Successful response:
+
+```json
+{
+  "id": 24,
+  "survey": "customer-feedback",
+  "submitted_at": "2026-05-02T12:00:00+00:00",
+  "thank_you_message": "Thanks for your response."
+}
+```
+
+## Answer Formats
+
+List style:
+
+```json
+{
+  "answers": [
+    {
+      "question": "name",
+      "value": "Alex"
+    }
+  ]
+}
+```
+
+Object style:
+
+```json
+{
+  "answers": {
+    "name": "Alex",
+    "score": 5,
+    "subscribe": true
+  }
+}
+```
+
+Choice answers accept either the choice `value` or choice `id`.
+
+## Validation
+
+- Required questions must be answered.
+- Unknown question slugs are rejected.
+- Duplicate answers for the same question are rejected.
+- Rating answers must be numeric and inside the configured range.
+- Yes/no answers accept booleans or `yes`, `no`, `true`, `false`, `1`, `0`.
+- Closed, draft, expired, or not-yet-started surveys reject responses.
+
+## Environment Variables
+
+- `DJANGO_SECRET_KEY`: required for production deployments.
+- `DJANGO_DEBUG`: set to `0` in production.
+- `DJANGO_ALLOWED_HOSTS`: comma-separated host list. Defaults to `*`.
+- `SURVEY_API_CORS_ORIGINS`: comma-separated origin list for `/api/`.