193 lines
3.7 KiB
Markdown
193 lines
3.7 KiB
Markdown
# 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/`.
|