This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Health api

1 - health-api Specification

Provide a runnable HTTP foundation for the MLOps course with a health check, an inspectable API description, and independent application instances.

The service SHALL respond to GET /health with HTTP 200 and the JSON object {“status”: “ok”}. The response SHALL indicate that the HTTP application is running without invoking recommendation computation or external services.

  • WHEN a client sends GET /health to a running service
  • THEN it receives HTTP 200 with application/json content and {“status”: “ok”}

The service SHALL provide a valid OpenAPI document at GET /openapi.json, including the health endpoint and its successful response contract. It SHALL provide the default documentation pages at /docs and /redoc, configured to use that schema URL.

  • WHEN a client requests GET /openapi.json
  • THEN it receives HTTP 200 with a valid OpenAPI JSON document describing GET /health and its successful JSON response
  • WHEN a client requests GET /docs or GET /redoc
  • THEN it receives HTTP 200 with an HTML documentation page referring to /openapi.json

Future application endpoints SHALL use /api/v1 as their initial routing prefix. Recommendations SHALL be exposed under that prefix; health and default API documentation SHALL retain their agreed root paths.

  • WHEN a client requests GET /api/v1/predict
  • THEN the service responds with HTTP 404 rather than exposing prediction or placeholder business behavior

Constructing an application SHALL create fresh application and routing state. Importing application modules SHALL NOT start a server, create shared mutable application instances, or allocate external service resources. Changes to one application’s routing SHALL NOT affect another application’s routing.

  • WHEN two applications are constructed in one process and routing is subsequently added to one of them
  • THEN the other application’s routes remain unchanged

Requirement: Provide a configurable local server entry point

The service SHALL be runnable through a repository Bazel target with configurable host and port. It SHALL bind to 127.0.0.1:8000 by default, accept an explicitly selected loopback address and available port, and shut down cleanly on termination.

  • WHEN the server target starts with a loopback host and an available port
  • THEN the health and OpenAPI endpoints are served on that address
  • AND terminating the server releases its resources and listening socket

GET /api/v1/recommend SHALL accept a required track_name query and an integer n query defaulting to 5, constrained to 1 through 20. It SHALL return a RecommenderRecommendationResponse with requested_track and recommendations of RecommenderSong (track_name, artists, album_name). It SHALL use the upstream load_model function to load the declared model.pkl during application lifespan, with per-application state and no global model object.

  • WHEN a client requests a track in the trained model with n=3
  • THEN it receives HTTP 200 and three typed song recommendations
  • AND requested_track matches the query
  • WHEN n is 0, 21, or nonnumeric, or track_name is absent
  • THEN the response is HTTP 422
  • WHEN track_name does not exist in the model
  • THEN requested_track is preserved and recommendations is empty