Last updated Aug 13, 2024

API Contract

When a cache-miss for this key + record-type occurs, TCS makes a HTTP GET request to your backing-store, like: GET /entity/<recordType>/<key> (client calls TCS) → GET https://<baseUrlForRecordType>/<key> (URI of request to your service)

Note - can contain / e.g. ari::cloud/abc123 - it is passed on exactly as given by the caller of TCS.

Valid Response Codes

Response codes for read-through endpoints mirror the TCS API.

200 (OK) - Content exists for <key>, JSON returned in body should be cached.
404 (Not Found) - No content exists for <key>.

Any other response status (e.g. 400) will be treated as an unexpected error, map to a 500 status-code returned to TCS clients. Our 5xx alert thresholds are high (service-descriptor.sd.yml), but may eventually fire.

We expect backing store providers to monitor their TCS endpoints.

Exptected Response Headers

At minimum, response headers must include (additional headers are allowed)

Content-Type - standard HTTP header
- Recommended: application/json (most TCS data is JSON)
- :warning: Defaults to application/octet-stream if absent. TCS can store arbitrary
Last-Modified - standard HTTP header following rfc7232#section-2.2 (not an integer)
version - a positive, monotonically increasing number (used for invalidation logic)
- Ideally this mirrors a version number in your datastore, but an integer timestamp will also work

Read-timeouts and retries

TCS will make 3 attempts in total to load a key from your backing-store. The backing-store HTTP Client is configured such that:

each attempt uses a 5000ms timeout
between attempts, the retry interval is 500ms
the initial connection request timeout is 3000ms

Note - slow backing-store responses may be directly observed by consumers on cache miss.

Example Response

1
2
HTTP/1.1 200 OK
Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
Content-Type: application/json
version: 101
{
  "some-json": "value"
}