Terminology Cache Adapter - API Contract

GET /api/v1/terminology-cache/api/v1/terminology-cache

List all cached terminology entries with their timestamps

Auth Required org_adminglobal_admin

Response Example

{
  "data": [
    {
      "organization_id": "org_nhf_oslo",
      "label_count": 18,
      "cached_at": "2026-03-26T06:00:00.000Z",
      "expires_at": "2026-03-26T18:00:00.000Z",
      "is_expired": false
    },
    {
      "organization_id": "org_hlf",
      "label_count": 14,
      "cached_at": "2026-03-24T12:00:00.000Z",
      "expires_at": "2026-03-25T00:00:00.000Z",
      "is_expired": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 7
  }
}

GET /api/v1/terminology-cache/api/v1/terminology-cache/:organization_id

Read cached label map for an organization (maps to read()). Returns null if not cached.

Auth Required coordinatororg_adminglobal_admin

Response Example

{
  "organization_id": "org_nhf_oslo",
  "labels": {
    "role.coordinator": "Programleder",
    "role.peer_mentor": "Aktivitetsvenn",
    "activity_type.group_walk": "Fellestur",
    "activity_type.café_visit": "Kafé-besøk"
  },
  "cached_at": "2026-03-26T06:00:00.000Z",
  "expires_at": "2026-03-26T18:00:00.000Z",
  "is_expired": false
}

POST /api/v1/terminology-cache/api/v1/terminology-cache

Write a label map into the cache for an organization with a given timestamp (maps to write())

Auth Required org_adminglobal_admin

Request Example

{
  "organization_id": "org_nfb_bergen",
  "labels": {
    "role.coordinator": "Koordinator",
    "role.peer_mentor": "Likeperson",
    "activity_type.group_walk": "Gruppetrim"
  },
  "source_timestamp": "2026-03-26T10:10:00.000Z",
  "ttl_seconds": 43200
}

Response Example

{
  "organization_id": "org_nfb_bergen",
  "label_count": 3,
  "cached_at": "2026-03-26T10:15:00.000Z",
  "expires_at": "2026-03-27T10:15:00.000Z"
}

PUT /api/v1/terminology-cache/api/v1/terminology-cache/:organization_id

Update or extend a cache entry for an organization

Auth Required org_adminglobal_admin

Request Example

{
  "labels": {
    "role.coordinator": "Gruppeansvarlig",
    "role.peer_mentor": "Aktivitetsvenn"
  },
  "source_timestamp": "2026-03-26T10:12:00.000Z",
  "ttl_seconds": 86400
}

Response Example

{
  "organization_id": "org_nhf_oslo",
  "label_count": 19,
  "cached_at": "2026-03-26T10:15:30.000Z",
  "expires_at": "2026-03-27T10:15:30.000Z"
}

DELETE /api/v1/terminology-cache/api/v1/terminology-cache/:organization_id

Evict cached terminology for an organization, forcing next read to fetch from source (maps to evict())

Auth Required org_adminglobal_admin

Response Example

{
  "organization_id": "org_nhf_oslo",
  "evicted": true,
  "evicted_at": "2026-03-26T10:16:00.000Z"
}

GET /api/v1/terminology-cache/api/v1/terminology-cache/:organization_id/timestamp

Read the source data timestamp stored in the cache entry (maps to readTimestamp())

Auth Required coordinatororg_adminglobal_admin

Response Example

{
  "organization_id": "org_nhf_oslo",
  "source_timestamp": "2026-03-26T06:00:00.000Z",
  "cached_at": "2026-03-26T06:01:12.000Z",
  "is_expired": false
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}