fix: normalize REST paths, add security scheme, fix schema issues, add CI

[jeremi]

Summary

This PR brings the Scheduler BB OpenAPI spec in line with its own cross-cutting requirements and standard REST/OpenAPI conventions.

No new endpoints are added. Two endpoints are removed (PUT and DELETE on /log) because mutable audit logs contradict the spec's own audit logging requirements (sections 5.1.3 and 6.9). The remaining 35 operations map 1:1 to the original 35 (excluding the 2 removed).

Changes were validated with Spectral (0 errors, 0 warnings) and the OpenAPI spec validator. A GitHub Actions workflow is included to prevent regressions.

What changed

API paths (breaking)

All paths are normalized from RPC-style to REST conventions:

Before	After
POST /event/new	POST /event
PUT /event/modifications?event_id=X	PUT /event/{event_id}
DELETE /event?event_id=X	DELETE /event/{event_id}
GET /event/list_details?qry={...}	POST /event/search (body)

Same pattern applied to all 9 resource types. Resource IDs moved from query params to path params. Creation and search payloads moved from qry query param (nested objects that cannot be serialized in URLs) to requestBody.

Security (breaking)

• Added bearerAuth security scheme (HTTP bearer, JWT format) per section 5.1.4
• Applied globally to all operations
• Removed requestor_id and request_token query parameters (tokens in query strings appear in logs, browser history, and proxy caches)

Schema fixes

• subscriber_limit: string to integer (event schemas)
• lat/long in venue: string to number
• format: url to format: uri (all URL fields), with valid URI examples
• Boolean examples: "true" to true (appointment schemas)
• free_slots: replaced malformed string with time_slot object array
• days_hours.day_of_week example: "[monday" to "monday"
• Array examples in 8 filter schemas: strings to actual arrays
• free_resource_filter.Entity_id casing to entity_id
• Normalized wrapper key in *_new_qry schemas to details (matching *_modify_qry)

Event slot model

Extracted a shared time_slot schema ({from, to} datetime pair). Used in:

• event_creation_details.slots (array, multi-slot creation)
• event_details.slot (single slot per event)
• free_resource_details.free_slots

This resolves the inconsistency where creation used an inline slots array but read/update used flat from/to fields.

Response codes and required fields

• POST create: 200 to 201 Created
• DELETE: 200 to 204 No Content
• Added 401 and 500 responses to all operations
• Added required arrays to 9 creation/detail schemas (derived from spec section 7)

Pagination

All 10 search endpoints now return a {data, pagination} envelope with page, page_size, and total. Query parameters page (default 1) and page_size (default 20, max 100) are defined as reusable components.

Audit log integrity

Removed PUT /log/{log_id} and DELETE /log/{log_id}. The spec mandates audit logging (5.1.3 REQUIRED, 6.9) but the API allowed arbitrary modification and deletion of log records. Logs are now append-only + read-only.

Spec markdown

• Fixed section numbering in 8-service-apis.md: 4.10-4.13 to 8.10-8.13
• Updated all 35 swagger blocks to reference new paths/methods, removed 2 for deleted log endpoints
• Updated all endpoint references in Mermaid diagrams in 9-workflows.md
• Fixed SubscriberLimit type in 7-data-structures.md: String to Integer

CI

• .spectral.yml with 7 custom rules + 3 built-in rules
• .github/workflows/validate-api.yml triggered on changes to api/ or .spectral.yml
• Warns on stale API files in spec/.gitbook/assets/

Housekeeping

• Replaced hardcoded test server URL with parameterized template
• Removed empty api/test.txt
• Removed 10 orphaned *_list schemas (replaced by pagination envelope)
• Fixed tag mismatch: subscribers to subscriber
• Fixed subscriber/search response description (said "message list")
• Added operationId to all 35 operations
• Added description field to all 35 operations

Breaking changes

This PR changes every path and removes query-string auth. Any existing client code, test harness, or integration would need to update.

The Gherkin test harness in test/ references the old paths and would need corresponding updates. That work is not included here to keep the PR focused on the spec itself.

Not in scope

• 4 missing interfaces (Information Mediator, PubSub, Messaging, Admin): The spec text acknowledges these as deferred ("should be the purpose of a next iteration"). These are scope gaps, not quality issues.
• Stale API files in spec/.gitbook/assets/: 5 files with an older 33-path version. These may be managed by GitBook. After merge, the swagger blocks in 8-service-apis.md load from the main branch raw URL; if GitBook uses checked-in assets instead, there may be a visual inconsistency in published docs.
• Structured error response schema: Error responses have descriptions but no response body schema. A shared error object would improve the spec further but is a separate concern.
• 409 Conflict for deduplication: Sections 6.1 and 6.2 require duplicate detection, but no endpoint defines a conflict response. Worth adding in a follow-up.

Feedback requested

1. required arrays on creation schemas: These are derived from spec section 7 but some are ambiguous. In particular, subscriber_details only requires ["name"], which may be too conservative. Please review and adjust.
2. Gherkin test harness: The tests reference old paths. Happy to submit a follow-up PR updating the test suite if this direction is accepted.
3. GitBook assets: Should the stale files in spec/.gitbook/assets/ be removed in this PR or left for GitBook to regenerate?

Validation

• Spectral: 0 errors, 0 warnings
• openapi-spec-validator: VALID
• All $ref pointers resolve, no orphaned schemas