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-congestionsThe 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.