If I'm not mistaken there are a lot of endpoints that are cached, so the result might be off by up to 5 minutes or so.
It would be really helpful if that could be reflected by header values, so it is transparent if / when / how long data is cached.
1. I access https://api.guildwars2.com/v2/account/raids to get the raid progress. The first call takes a bit longer than subsequent calls, sometimes 5000 vs 100 ms, so I assume the first call has fresh data, subsequent not.
2. I finish a raid encounter.
3. I access /account/raids again, but the just finished encounter is missing.
4. I have to poll /account/raids for up to 5 minutes to see the updated encounter list.
What that implies is that whenever I read such data, I have to delay for at least 5 minutes and read the data again, to be sure that the data is current and not cached.
1. Add a header value indicating the "age" of the data. I first thought of the "Last-Modified"-Header you recently added to some endpoints. (But maybe a different header would be more useful, see explanation below)
2. In cases where you know the caching timings, add an "Expires" header. If the resource was cached at 12:00:00 and I access it at 12:01:00, the "expires" Header could be 12:05:00, so I would know that polling the resource for the next 4 minutes would be of no value, reducing your server load.
3. That would also mean that caching mechanisms like "If-Modified-Since" would work. A 304 for a large resource like /account/achievements would also reduce server load quite a lot.
Last-Modified or other Header?
There is a scenario where it would be better to use a separate header than Last-Modified, because both informations (cache date and actual modification date) are needed.
"This achievement list did not change since 5 days" and "this achievement list is from 2 minutes ago, so fairly up to date but not entirely fresh" are two completely different informations that are both valuable.
If I use an endpoint like /account/achievements, which can be quite large and expensive to build / parse, using the If-Modified-Since mechanism can be quite powerful. That means I want to get a 304 as much as possible until the locally cached version did not change. But I still want to know if the resource is fresh or deprecated, for reasons stated above. With 2 different headers I could