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!! <3

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