Design API

[rikedyp]

Draft the rough OpenAPI 3.1 specification for the target API.

GET:

• GET /videos — search/filter/paginate
• GET /videos/{youtube_id} — single video
• GET /videos/recommended — recommendations
• GET /table/{table} — generic table read (adopt the parameterised pattern from the stark branch)
• GET /table/{table}/{id} — single row by ID
• GET /presenters — distinct presenter names
• GET /dtv_events — events with videos
• GET /version — version string

Write side (redesign with proper REST verbs):

• POST /person (create), PUT /person/{id} (update), DELETE /person/{id}
• Same pattern for /organisation, /event, /event_type, /presentation_type, /category
• POST /presentation (create), PUT /presentation/{id} (update), DELETE /presentation/{id}
• POST /presentation/{id}/material (add material)
• POST /admin/refresh — trigger cache rebuild
• POST /admin/wp-push — push to WordPress

Decisions to make during this issue:

• API versioning prefix (/v4/...) — yes or no?
• Response envelope standardisation — keep mixed format or unify?
• Error response schema

To do

•  Outline spec committed to docs/
•  All GET and write endpoints specified with request/response schemas
•  Error responses defined
•  Envelope and versioning decisions documented

[rikedyp]

Suspect the recommendations endpoint might be better as a query parameter or additional path to the {youtube_id}, but think whether we ever want to return multiple videos' recommendations in a single query I suppose.

[rikedyp]

fixed in 1c386a7