Use Case

Using ETag for getting a congestion snapshot

An Etag is an identifier for a specific version of data. You should retain the latest ETag value you receive. 

The next time you call the same API to get data, you should use the If-None-Match request header along with the retained ETag value, so that the API will send back a full response if and only if the data changes.

 

Step 1: First call, with no ETag yet.

GET
https://api.myptv.com/flows/realtime-congestions/v1/realtime/get-congestions

The response has the full data and an ETag header, with the value "0x8DE5A1C2B3D4E5F".

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "0x8DE5A1C2B3D4E5F"
{
 "congestions": [
   {
     "id": 1,
     "uuId": "3f6c2a9e-1b7d-4c55-9a0e-2d8f4b1c7e01",
     "timestampEpoch": 1759305600,
     "name": "Via Tuscolana",
     "severity": 0.65,
     "usuality": 0.31,
     "lengthM": 1270.5,
     "...": "..."
   }
 ]
}

 

Step 2: Make a call with the kept ETag in If-None-Match

GET https://api.myptv.com/flows/realtime-congestions/v1/realtime/get-congestions
If-None-Match: "0x8DE5A1C2B3D4E5F"

If the data has not changed, the API sends a response without a body:

HTTP/1.1 304 Not Modified
ETag: "0x8DE5A1C2B3D4E5F"

Therefore, keep using the data you already have, and keep the same ETag.

If the data has changed, the API sends a full response with a new ETag:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "0x8DE5A1C9F0E1D2C"
{ "congestions": [ ... ] }

Replace your data, and keep the new ETag ("0x8DE5A1C9F0E1D2C") for the next call.

 

Additional notes

  • The ETag must be used exactly as you received it, quotes included. 
  • A matching ETag doesn’t bypass the checks. The call can returns code 503 when the latest result is older than 15 minutes.
  • If the data changes to “no congestions”, the call returns code 204 No Content with a new ETag and without a body.