API - NIAEFEUP/tts-be GitHub Wiki
The TTS backend exposes a REST API consumed by the frontend. All endpoints are served at https://tts-dev.niaefeup.pt/api in development and https://tts.niaefeup.pt/api in production.
Documentation
The API is documented in Postman, split by module:
| Module | Description | Postman docs |
|---|---|---|
| Faculties | List faculties at UPorto | View |
| Courses | List courses by faculty | View |
| Course Units | List course units by course | View |
| Schedule | Get schedule slots for a course unit | View |
Testing with Postman
You can import any of the collections above directly into Postman and run requests against your local backend.
- Open Postman and click Import
- Paste the Postman collection URL
- Set the base URL variable to
https://tts-dev.niaefeup.pt/api - Make sure the backend is running (
docker compose up) before sending requests
Most read endpoints are unauthenticated. Endpoints that require login (e.g. saving a schedule, exchange operations) need a valid session cookie — log in through the browser first, then copy the cookie into Postman using the Cookie Jar or a request header.
Architecture
The codebase follows a strict layering pattern:
Request → View (HTTP only) → Controller (all logic) → Model (data only)
- Views (
views/) handle HTTP: parse the request, call a controller, return a response. No business logic here. - Controllers (
controllers/) contain all business logic: validation, database queries, data transformation. - Models (
models/) define the database schema using Django ORM. No logic beyond field definitions and simple properties. - Serializers (
serializers/) convert model instances to/from JSON for the API responses.
When adding a new endpoint, always put the logic in the controller, not the view.
Common patterns
Paginated list endpoint:
GET /api/courses/?faculty_id=1&page=1
Detail endpoint:
GET /api/course-units/12345/
Authenticated endpoint (session cookie required):
POST /api/exchanges/
Authorization: via session cookie set on login
Changelog
- 2022-07-27: Transferred documentation to Postman and OpenAPI v3.0
- 2022-08-19: Removed OpenAPI v3.0 spec (was out of date)