DEV Community

Sukriti Vohra
Sukriti Vohra

Posted on Edited on

Kadamba Footage Archive: Catalogue API and Health Checks

Illustrative proposed reference — not a verified production contract. Prepared for Vasanthi Iyer and the nine cataloguing and rights staff at Kadamba Footage Archive, Mysuru, and for outside clients. Kadamba reports 48,000 clips and 1,120 hours of digitised footage. No OpenAPI document or Kadamba UptimeRobot export was available, so the hostnames, routes, sample records, monitor names, and access rules below are realistic placeholders. The reserved .example addresses are not live services. Replace them and obtain technical sign-off before client integration.

Catalogue and rights endpoints

Proposed API base: https://api.kadamba-footage-archive.example/v1

Use JSON, stable clip IDs, and ISO 8601 dates. per_page controls page size; q searches title, subject, and description text.

Method and path Plain-English purpose Proposed audience
GET /v1/clips Search and page through the catalogue Staff and clients
GET /v1/clips/{clip_id} Read one clip's technical and descriptive metadata Staff and clients
PATCH /v1/clips/{clip_id} Change selected cataloguing fields Cataloguing staff
GET /v1/clips/{clip_id}/rights Read clearance and licensing status Staff; client visibility TBD
PUT /v1/clips/{clip_id}/rights Replace a rights record Rights staff
GET /health/live Answer whether the API process is alive Monitoring
GET /health/ready Answer whether required dependencies are ready Monitoring and operations

Search the catalogue

GET /v1/clips?q=monsoon&page=1&per_page=2

Illustrative 200 OK response:

{
  "data": [
    {
      "clip_id": "KFA-000138",
      "title": "Mysuru market after monsoon rain",
      "date": "1987-06-14",
      "duration_seconds": 92,
      "source_format": "16mm film",
      "rights_status": "review_required"
    },
    {
      "clip_id": "KFA-001204",
      "title": "Kaveri flood-response newsreel",
      "date": "1992-08-03",
      "duration_seconds": 148,
      "source_format": "U-matic",
      "rights_status": "cleared_subset"
    }
  ],
  "page": 1,
  "per_page": 2,
  "total": 2
}
Enter fullscreen mode Exit fullscreen mode

Read one clip

GET /v1/clips/KFA-000138

{
  "clip_id": "KFA-000138",
  "title": "Mysuru market after monsoon rain",
  "date": "1987-06-14",
  "duration_seconds": 92,
  "digitised": true,
  "preservation_format": "FFV1/MKV",
  "access_format": "H.264/MP4",
  "subjects": ["Mysuru", "markets", "monsoon"],
  "rights_status": "review_required"
}
Enter fullscreen mode Exit fullscreen mode

A successful catalogue update could return:

{"clip_id":"KFA-000138","updated":true,"catalogue_record_version":17}
Enter fullscreen mode Exit fullscreen mode

Read or update rights

GET /v1/clips/KFA-000138/rights

{
  "clip_id": "KFA-000138",
  "status": "review_required",
  "client_licensing": "not_available_until_cleared",
  "credit": "Kadamba Footage Archive; donor credit pending",
  "territories": [],
  "review_owner": "rights-team"
}
Enter fullscreen mode Exit fullscreen mode

A successful rights update could return:

{"clip_id":"KFA-000138","updated":true,"rights_record_version":9,"status":"review_required"}
Enter fullscreen mode Exit fullscreen mode

A rights status is a workflow signal, not a licence. Clients should wait for written licensing confirmation.

Server health endpoints

GET /health/live should be cheap and should not depend on every downstream service:

{"status":"ok"}
Enter fullscreen mode Exit fullscreen mode

GET /health/ready can report whether the service is ready to accept catalogue traffic:

{
  "status": "ok",
  "checks": {
    "catalogue_index": "ok",
    "metadata_store": "ok",
    "preview_storage": "ok"
  }
}
Enter fullscreen mode Exit fullscreen mode

Keep stack traces, secrets, internal hostnames, and client details out of health responses.

UptimeRobot check names

These are proposed display names, not a claim that the monitors currently exist. Suggested settings are HTTPS with SSL validation, a five-minute interval, and a 30-second timeout. Check for HTTP 200 and, where practical, a small response keyword. Do not run destructive PATCH or PUT requests as uptime checks.

  • Kadamba | Catalogue Search | HTTPS + SSL — /v1/clips?q=monsoon&per_page=1
  • Kadamba | Clip Metadata | HTTPS + SSL — /v1/clips/KFA-000138
  • Kadamba | Rights Lookup | HTTPS + SSL — /v1/clips/KFA-000138/rights
  • Kadamba | API Liveness | HTTPS + SSL — /health/live
  • Kadamba | API Readiness | HTTPS + SSL — /health/ready

Monitoring service: UptimeRobot.

Authentication: confirm with Irfan Pasha

Before treating this as integration documentation, Irfan Pasha should confirm:

  • the actual scheme and header—API key, Bearer token, OAuth 2.0, or another method;
  • staff, rights-staff, and client scopes, including whether clients may see rights summaries;
  • whether readiness and detailed health results must be private;
  • credential issuance, expiry, rotation, revocation, rate limits, and the real 401/403 payloads;
  • whether monitors need credentials and how those secrets are stored.

Never put real credentials in query strings, sample JSON, screenshots, monitor names, this article, or bookmarks. All examples here are credential-free placeholders.

Top comments (0)