ESI Endpoint Versioning: Important Info and Best Practices

ESI Endpoint Versioning: Important Info and Best Practices

This blog post is part of a series of blogs examining best practices for ESI development. Each blog will be published on the 8th of each month during the journey towards XML API and CREST’s termination date. The legacy APIs will be terminated on May 8th, 2018, or earlier if metrics signal a trivial level of usage.

---

We'd like to start this blog with an important announcement that will affect a large swath of EVE third party developers

On December 20th, 2017, the following dev routes will be promoted to latest:

• GET /v3/alliances/{alliance_id}/
• GET /v2/alliances/names/
• GET /v3/characters/{character_id}/assets/
• GET /v3/characters/{character_id}/clones/
• GET /v2/characters/{character_id}/online/
• GET /v2/characters/{character_id}/roles/
• GET /v3/characters/{character_id}/search/
• GET /v4/characters/{character_id}/skills/
• GET /v3/characters/{character_id}/wallet/journal/
• POST /v2/characters/{character_id}/assets/locations/
• POST /v4/characters/{character_id}/cspa/
• DELETE /v2/characters/{character_id}/contacts/
• GET /v4/corporations/{corporation_id}/
• GET /v2/corporations/{corporation_id}/assets/
• GET /v3/corporations/{corporation_id}/members/
• GET /v2/corporations/{corporation_id}/wallets/{division}/journal/
• GET /v2/corporations/names/
• POST /v2/corporations/{corporation_id}/assets/locations/
• GET /v2/search/

This means any software not using the numbered versions of these routes will suffer from backwards incompatible changes on December 20th. To avoid disruption, we offer the following checklist:

1. Check to make sure your software is only calling versioned ESI routes. (e.g v1, not latest, dev or legacy).

2. Check to make sure that your code is not using any versioned routes labelled only as legacy from the above list.

3. Optionally, upgrade to the versioned routes above (currently labelled as dev) and make the necessary changes to your code. This is highly suggested.

Read on for more in depth instructions.

How ESI routes are versioned

Before digging deeper into the above checklist it is best to do a recap on the lifecycle of a route. The following is a diagram showing how a route is versioned and labelled from its inception:

This diagram should show you why it is bad to use the legacy, latest or dev labels directly in your ESI URLs and why you should always use versioned routes. If you're using labels in your URLs the spec underneath those labels changes dramatically during route promotion.

December 20th Checklist

1. Check to make sure your software is only calling versioned ESI routes.

Not only should you do this for the above 19 routes, but it's best if you use the versioned alternative for all ESI routes inside your software. This is as simple as doing a find and replace on the ESI URLs you are calling.

Good: https://esi.tech.ccp.is/v2/alliances/{alliance_id}/
Not good: https://esi.tech.ccp.is/latest/alliances/{alliance_id}/

2. Check to make sure that your code is not using any versioned routes labelled only as legacy.

Here is a list of versions of the above 19 routes that will start 404'ing on December 20th:

• GET /v1/alliances/{alliance_id}/
• GET /v1/characters/{character_id}/assets/
• GET /v1/characters/{character_id}/search/
• GET /v2/characters/{character_id}/skills/
• GET /v1/characters/{character_id}/wallet/journal/
• GET /v2/corporations/{corporation_id}/

If you are currently using any of these versioned routes (thanks for using versions!) in your code then you will have to update your code to support a current version before December 20th.

If you want to know if any of the other versioned routes you are depending on are considered deprecated there are two ways to do that:

1. Look at https://esi.tech.ccp.is/ui/?version=legacy. Any routes that have a strike through their paths will be deleted next time a new version is promoted to latest.

2. Watch for a Warning HTTP header. This header informs you that the route you are using has been deprecated.

3. Optionally, upgrade the above 19 routes to their dev versions

If you update your software to use all the versioned routes listed above then your software will be even more future proofed! However, bumping up to a new version means that the spec has changed and you will have to modify your code to deal with that. Luckily, Team Tech Co. just released a new UI to help you see a diff between all routes under specific labels or versions: https://esi.tech.ccp.is/diff/latest/dev/.

If a route has a new version available in dev it will also now show in the ESI UI like this:

Clicking that hyperlink will take you to the new diff UI for the given route.

Why mass promote all these 19 routes to latest?

As was shown in the route lifecycle diagram, the time that a versioned route is supposed to be labelled with dev should be six weeks before it's promoted to latest. Why are there 19 routes that have not been promoted to latest then? The simple answer is that during the race to parity we forgot to promote some endpoints along the way. The mass promotion on December 20th is our way to correct this oversight and restart the proper promotion workflow. We are actively developing internal tools to help us keep on top of this in the future.

A reminder for those using swagger codegen

If you are automatically generating clients using Swagger codegen, remember to ALWAYS use the "underscore" ESI swagger.json route when choosing a URL to generate a client from. As an example, instead of using https://esi.tech.ccp.is/latest/swagger.json, use https://esi.tech.ccp.is/_latest/swagger.json. Notice the _ placed before "latest" in the latter URL. This will make your auto generated client use the versioned routes instead of labels in its ESI URLs. Remember you can also generate a client using the versioned routes from both dev and legacy by using _dev or _legacy like _latest was used in the example.

Conclusion

In conclusion:

• On December 20th there will be a mass promotion of all versioned routes currently in dev (approximately 19 of them) to latest.
• This mass promotion will affect you if any of your code is using latest in the URL for any of those 19 routes.
• Follow the checklist given to ensure a smooth transition.

As always, you can discuss all things ESI on the tweetfleet slack (use this link to join) in the #esi channel.

o7

-- Team Tech Co.

Appendix

The following paths have been added or updated in ESI since the previous blog:

• GET https://esi.tech.ccp.is/ui/#/Assets/get_characters_character_id_assets)
• GET https://esi.tech.ccp.is/ui/?version=dev#/Assets/get_characters_character_id_assets)
• GET https://esi.tech.ccp.is/ui/#/Corporation/get_corporations_corporation_id_outposts)
• GET https://esi.tech.ccp.is/ui/#/Corporation/get_corporations_corporation_id_outposts_outpost_id)
• GET https://esi.tech.ccp.is/ui/?version=dev#/Assets/get_corporations_corporation_id_assets)

Get a sneak peek at what's coming to ESI by watching our deployment timeline

Migrating from the XML API? Find equivalent ESI routes to the XML API.

Migrating from CREST? Find Equivalent ESI routes to CREST

back