Hello all,

I have been making some recent changes to the way that API content is updated that allows more developers into the process. The goal is to make missing data (such as nodes) less frequent. As such, the nodes list is updated and has been moved to a new url (more details below).

With these changes comes new code and potentially new bugs especially with having the new code mimic the way the old API works, so if you find any bugs or inconsistencies, I'd love to hear about them.

Also, in order to make it easier to tell if daily/weekly progress has been reset (e.g. raid clears), I've added last_modified to account and character endpoints. This removes the need to poll & store the account age field (which allows serverless apps to monitor progress properly).

Finally, I've introduced schema versions for updated endpoints. The motivation is to prevent breaking existing apps while still allowing the API to be modified without fear. Find more details on how to use them below.

Recent API Updates

First, here are the changes in list format:

Several endpoints under v2/account and v2/characters now return a Last-Modified header. They respect If-Modified-Since requests and will properly return a 304 Not Modified.

and now return a Last-Modified header. They respect If-Modified-Since requests and will properly return a 304 Not Modified. v2/account , v2/characters/:id now have a last_modified field in the latest schema.

, now have a field in the latest schema. v2/nodes has moved to v2/home/nodes . The old endpoint is still available.

has moved to . The old endpoint is still available. v2/cats has moved to v2/home/cats . The old endpoint is still available.

has moved to . The old endpoint is still available. v2/account/home/nodes now contains all home instance nodes including the garden plots.

now contains all home instance nodes including the garden plots. v2/account/home/cats has an updated schema that is consistent with other similar endpoints.

Schema Versions

Modifying the schema of an endpoint causes breakage for existing apps. This is especially bad for things like mobile apps where developers cannot force their users to update the same way web apps can.

To allow API flexibility without paralyzing its development, I have added the notion of schema versions to endpoints that change. They are meant to prevent an app from hard crashing due to schema failure by migrating data backward from the latest version down to the requested version.

This approach isn't fool-proof: If a later schema version has less information than the current nominal path, then the migration will have to invent some data, which can still cause app breakage, just in a different way.

Schema versions can be requested with a v query param or an X-Schema-Version request header. Schema versions are comparable strings that happen to be ISO 8601 datetimes which means string compares are chronological.

Here is an example of making a request with a requested schema version:

fetch('https://api.guildwars2.com/v2/account', {headers: { 'X-Schema-Version': "2019-02-21T00:00:00Z", 'Authorization': `Bearer ${my_api_key}`} }) .then((r) => r.json()) .then((data) => console.log(data.last_modified));

Here is another example using query params:

fetch(`https://api.guildwars2.com/v2/account?v=latest&access_token=${my_api_key}`) .then((r) => r.json()) .then((data) => console.log(data.last_modified));

Using Schema Versions

Here is the standard approach to using schema versions in your app:

When creating your app, create a static schema version (the ISO 8601 formatted date you start working) to send with all of your requests. If the API changes suddenly one day, your app should be mostly unharmed because your app will still be requesting the same schema.

When you update your app, bump the static schema version up to that day's date and check for schema breakage before release.

If you don't care about your app breaking, or you're developing locally, you can use latest as your schema version and always get the latest schema from the API.

I'd love to hear your thoughts on all of this .

Thanks!

Snider