136 lines
2.7 KiB
Markdown
136 lines
2.7 KiB
Markdown
# dg-surv
|
|
|
|
A Django survey API service with an admin panel for building surveys and public
|
|
JSON endpoints for anonymous responses.
|
|
|
|
## What is included
|
|
|
|
- Welcome page at `/`
|
|
- Browser documentation at `/docs/`
|
|
- Modern Django admin styling for survey management
|
|
- Public survey schema API
|
|
- Anonymous response submission API
|
|
- Built-in validation for text, choice, rating, and yes/no answers
|
|
- CORS headers for `/api/`
|
|
- Django tests for core API behavior
|
|
|
|
## 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: `http://127.0.0.1:8000/docs/`
|
|
- Admin panel: `http://127.0.0.1:8000/admin/`
|
|
- API index: `http://127.0.0.1:8000/api/surveys/`
|
|
|
|
## Creating a survey
|
|
|
|
1. Create a survey in the admin panel.
|
|
2. Add questions inline on the survey page.
|
|
3. For single-choice or multiple-choice questions, open the question record and
|
|
add choices.
|
|
4. Set the survey status to `Published`.
|
|
|
|
Supported question types:
|
|
|
|
- `short_text`
|
|
- `long_text`
|
|
- `single_choice`
|
|
- `multiple_choice`
|
|
- `rating`
|
|
- `yes_no`
|
|
|
|
## Public API
|
|
|
|
List published surveys:
|
|
|
|
```http
|
|
GET /api/surveys/
|
|
```
|
|
|
|
Read a survey schema:
|
|
|
|
```http
|
|
GET /api/surveys/customer-feedback/
|
|
```
|
|
|
|
Submit a response without authentication:
|
|
|
|
```http
|
|
POST /api/surveys/customer-feedback/responses/
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"respondent_email": "person@example.com",
|
|
"metadata": {
|
|
"source": "website"
|
|
},
|
|
"answers": [
|
|
{
|
|
"question": "name",
|
|
"value": "Alex"
|
|
},
|
|
{
|
|
"question": "experience",
|
|
"choice": "good"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`answers` can also be an object keyed by question slug:
|
|
|
|
```json
|
|
{
|
|
"answers": {
|
|
"name": "Alex",
|
|
"score": 5,
|
|
"subscribe": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Choice answers accept either the choice `value` or choice `id`.
|
|
|
|
## Documentation
|
|
|
|
Detailed API documentation is available in two places:
|
|
|
|
- Browser page: `http://127.0.0.1:8000/docs/`
|
|
- Markdown guide: [docs/API.md](docs/API.md)
|
|
|
|
## Configuration
|
|
|
|
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/`.
|
|
Defaults to `*`.
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
python manage.py test
|
|
```
|
|
|
|
## Project layout
|
|
|
|
```text
|
|
survey_service/ Django project settings and root URLs
|
|
surveys/ Survey models, admin, API views, tests, middleware
|
|
templates/ Welcome page, docs page, admin override
|
|
static/surveys/ Admin and public page styles/assets
|
|
docs/API.md Markdown API guide
|
|
```
|