Dev Insights Blog

Hi third-party devs,

As we started to upgrade the ESI infrastructure, making it more modern and easier for both you and us to work with, we have taken stock of our existing endpoint. To better enable us to focus on supporting the most used versions of a route and to start developing new endpoint, we must first clean up some of the old and underutilized versions of the routes. This blog post covers the detail of this process.

tl;dr: we will be removing old versions of routes. It is unlikely that these changes will affect you. Only a handful of applications and users are impacted, and we will be reaching out to them.

As you might know, all of our routes have versions. Whether it be /v1, /v2, /latest, /dev or even /legacy. When you make a call to ESI, you tell us which version you want to use, and we validate your input and return your output according to the schema attached to that version of the route. What you might not know, is that for most of the routes, all these different versions actually point to the exact same schema (both for input and output), even to the exact same piece of code. They are identical in every way. Only some (36 out of the 186, to be very exact) actually have a change in their schema from one version to the other. Delving deeper into this, we gather some fun statistics:

• 2 of those “new versions” only change the example.

• 13 of these “new versions” actually add a property or add a value to an enum.

For these 2+13 routes we will be changing the specifications of the older versions to match the newer. Yes, we know, it is not nice to change specifications of older routes. But as this is only about adding new properties/values to enums, we feel it is the better solution. According to the JSON Schema validation, which Swagger builds on top of, applications should not check if there are additional properties in an object other than the ones defined in the schema. As such, these extra properties should not cause any trouble. But, that said, any application that forces additionalProperties to be false will hit trouble on these versions of these routes. The alternative however is to remove these old (deprecated) versions. This feels like the wrong choice, especially as most applications won’t fail on additional properties in an object anyway.

That leaves us with 21 routes that actually have a breaking change between versions. Out of those 21, eight haven’t seen any traffic for over two weeks; so we can assume everyone migrated away from them, and we will be removing the old versions. That leaves us with 13 routes that we need to talk about. It has to be noted here that all these old versions have been deprecated for years.

Internally we have been discussing what to do here; do we keep serving two different versions of them, or can we remove the older one. Removing would mean it simplifies our code and infrastructure (by a lot, even). We delved into the actual traffic of those older versions on routes in order for us to make that call.

For completeness' sake, first the eight that haven’t seen traffic:

• GET /alliances/{alliance_id}/contacts/: breaking change from v1 → v2.

• POST /characters/{character_id}/assets/locations/: breaking change from v1 → v2.

• POST /characters/{character_id}/contacts/: breaking change from v1 → v2.

• PUT /characters/{character_id}/contacts/: breaking change from v1 → v2.

• GET /characters/{character_id}/skills/: breaking change from v3 → v4.

• POST /corporations/{corporation_id}/assets/locations/: breaking change from v1 → v2.

• GET /dogma/effects/{effect_id}/: breaking change from v1 → v2.

• GET /universe/factions/: breaking change from v1 → v2.

Next, two special ones:

• GET /characters/affiliation/: breaking change from v1 → v2. v1 returns a 404, where v2 returns a 400. Less than 1% of the calls to this route are for v1, and seemly nobody has hit a 404 in a long time. As such, we will change the v1 spec to match the v2. This isn’t the nicest thing to do, but again, the alternative would be to remove v1. We feel the difference in this error code is so minor, we rather continue to support those tools currently using v1.

• POST /characters/{character_id}/fittings/: breaking change from v1 → v2. Traffic is split 50/50 over v1 and v2. The only difference is the type of the input field flag. And difference in input fields we can process on our end. So, we made the unorthodox decision to make v2 accept the inputs of v1, and map v1 to v2 (so they become identical). This means all the tools using v1 will remain working (but will no longer be documented that they would).

As for the other 11:

• GET /characters/{character_id}/contacts/: breaking change from v1 → v2. Old version used by 2 characters.

• GET /characters/{character_id}/fittings/: breaking change from v1 → v2. Old version used by handful of characters.

• GET /characters/{character_id}/mail/labels/: breaking change from v2 → v3. Old version used by 1 application (which hasn’t seen any development in 6 years).

• GET /characters/{character_id}/online/: breaking change from v1 → v2. Old version used by 2 applications / handful of characters.

• GET /characters/{character_id}/orders/: breaking change from v1 → v2. Old version used by 2 characters.

• GET /characters/{character_id}/portrait/: breaking change from v1 → v2. Old version used by 5 characters.

• GET /corporations/{corporation_id}/contacts/: breaking change from v1 → v2. Old version used by 2 characters.

• GET /corporations/{corporation_id}/structures/: breaking change from v3 → v4. Old version used by 2 applications.

• GET /universe/stations/{station_id}/: breaking change from v1 → v2. Old version used by 1 application.

• GET /universe/system_kills/: breaking change from v1 → v2. Old version used by 1 characters.

• GET /universe/systems/{system_id}/: breaking change from v3 → v4. Old version used by 1 application.

As you can see, most older routes are used by very few people (and we are very grateful most of you already upgraded away from these older routes). But it also indicates that we have a lot of old code that we need to maintain for a very small part of our users that haven’t upgraded their apps. That made the decision easier: we decided to remove all those older versions from the eleven mentioned routes above.

In the next few days, we will be contacting those few characters and applications that we know how to reach, and explain what is happening. If they want to, we will even help them migrate away from the old route. As we appreciate so many of you already upgrading, the least we can do is help out those few left behind!

Currently the removal is planned for the 25th of March (a bit over 2 weeks). If you foresee any issue with this removal, please speak up in the #3rd-party-dev-and-esi channel on the EVE Discord. We will be listening.

Signing off,

CCP Pinky and the br CCP Stroopwafel

P.S. To give you an idea how little these versions of the routes are actually used, here an example of the above mentioned affiliation route. The yellow line is the old version, the green/blue are newer versions.