API updates - March 22 2019

[Daniel Snider.6241]

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.
• v2/account,v2/characters/:id now have a last_modified field in the latest schema.
• v2/nodes has moved to v2/home/nodes. The old endpoint is still available.
• v2/cats has moved to v2/home/cats. The old endpoint is still available.
• v2/account/home/nodes 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.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.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 :smile: .

Thanks!Snider

[Vegeta.2563]

There is one thing that's been bothering me ever since Path of Fire came out, and that map tiles haven't been updated since then. There is no map for Anything starting with Domain of Istan and onward.

[Awesumness.1823]

API updates get me excited in a special way.

Thank you for the updates and communication <3

[Illconceived Was Na.9781]

Thanks for the update.

Reminder for others:

• https://gitter.im/arenanet/api-cdi (@"Daniel Snider.6241" has been active on Glitter recently)
• https://github.com/arenanet/api-cdi/ (this has been less active as of late)

fixed: typo

[Immortius.4537]

Nice news, thank you for the update.I'm intrigued to see how the schema versioning plays out, especially in comparison to previous schema versioning (v1 vs v2 end points).

[Daniel Handler.4816]

@"Illconceived Was Na.9781" said:Thanks for the update.

Reminder for others:

• https://gitter.im/arenanet/api-cdi (@"Daniel Handler.4816" has been active on Glitter recently)
• https://github.com/arenanet/api-cdi/ (this has been less active as of late)

Wrong Daniel.

[Illconceived Was Na.9781]

@Daniel Handler.4816 said:

@"Illconceived Was Na.9781" said:Thanks for the update.

Reminder for others:

• https://gitter.im/arenanet/api-cdi
  (
  "Daniel Handler.4816"
  @"Daniel Snider.6241" has been active on Glitter recently)
• https://github.com/arenanet/api-cdi/
  (this has been less active as of late)

Wrong Daniel.

Oops. Fixed.

[Ideka.7946]

I would've thought that if you're changing the API in a way that's not backwards-compatible you would call it version 3 and put it under v3/...

The system described here makes me feel like there may be lots of API changes coming.

Either way, very nice to see the API get some love.

[Killerassel.2197]

Thank you! Both for the live sign and the updates. :heart:

The last_modified field was suggested in the forum and as stated in that thread, I have an idea I need it for. :+1:

@Ideka.7946 said:I would've thought that if you're changing the API in a way that's not backwards-compatible you would call it version 3 and put it under v3/...

Not necessarily. It depends on how strict you parse the responses. The json-to-object parser library I use doesn't care about additional fields, so the new last_modified would be silently ignored until I add it to the mapping. Others may throw an exception claiming the format was invalid. You wouldn't want to break, say, a mobile app without prior warning.

It does open the possibility to do breaking changes without major version bump, though. The inconsistency about the daily achievements / account type comes to mind.

[Renske.6178]

This is great!! <3Gets me all motivated to create some stuff with the API again. =D

[Ideka.7946]

@Killerassel.2197 said:Thank you! Both for the live sign and the updates. :heart:

The last_modified field was suggested in the forum and as stated in that thread, I have an idea I need it for. :+1:

@Ideka.7946 said:I would've thought that if you're changing the API in a way that's not backwards-compatible you would call it version 3 and put it under

v3/

...

Not necessarily. It depends on how strict you parse the responses. The json-to-object parser library I use doesn't care about additional fields, so the new last_modified would be silently ignored until I add it to the mapping. Others may throw an exception claiming the format was invalid. You wouldn't want to break, say, a mobile app without prior warning.

Well the changes proposed here are backwards-compatible as far as I can tell, just instead of putting the new version(s) under v3/ they're still under v2/, but must be specifically requested.

[Killerassel.2197]

After re-reading your post I think I understand what you meant.

Yes, the changes are indeed backward compatible because you need to explicitly request them. Whether as v=latest or v3/ is secondary. But as you said, v=latest is a good sign, because it allows for incremental changes without having a v3/ that is mostly empty or equal to v2/.

If they weren't guarded with ?v=... they would not have been backward compatible. I didn't realize it when I posted my comment, but I had to adapt my code regarding /account/home/cats, and as stated some code may complain about schema breaking, unexpected fields in responses.

[cawtx.2016]

how do you access/download the endpoint schema itself? I use python and the requests module to get the endpoint data.