Dev Insights Blog

Hi all,

Today we're announcing changes to the ESI endpoint versioning strategy. Moving forward, new routes will no longer rely on versions embedded in their URL paths. Instead, we are introducing an X-Compatibility-Date header that works for the entirety of the API. Existing routes also adopt this new behavior, but we will continue supporting the versioned URLs for the foreseeable future.

But why?

In the old model, each ESI route had its own independent versioning. One route could be on v4, another on v6, and a third on v1. This created unnecessary complexity and was especially unfriendly to newer developers. Updating code meant checking each route for changes, parsing changelogs for each route, and dealing with version numbers per route.

This method wasn't working well for us, so we set out to improve it. The updated model is simpler and should be much more intuitive to use. Instead of versioning every route independently, you now version your entire application against ESI at a specific date in time.

Introducing: Compatibility Dates

Every ESI request can now include an X-Compatibility-Date header using the ISO format - YYYY-MM-DD. This header tells ESI “This application was built or updated at this date - give me the API behavior as it was at that date”. If applications cannot set custom headers, the compatibility_date query parameter will do the same.

Since there is now only one “version”, and it is an actual date, upgrading becomes a lot easier to manage as well. You can easily compare your compatibility date to the changelog (since you no longer have to keep track of each individual route), and when you are satisfied with everything, you only have to change one X-Compatibility-Date value.

As ESI endpoints evolve, we will aim to maintain at least one year’s backwards compatibility. In some cases however, changes to backend services or underlying data structures necessitated by EVE’s development can make that impossible; in those cases we will announce deprecation and removal of unsupported versions separately and as early as we can.

Migration

Migration is entirely optional at this point. Existing versioned routes still work and will work for the foreseeable future. That said, all new routes we release will only support compatibility dates and will not be compatible with versioned URLs.

For those that want to migrate to the new system immediately, the flow is relatively simple:

1. Remove all version prefixes from the paths you call (i.e. /v1/status/ becomes /status/).

   1. Over the last few months we have merged all the different “v”-versions (including “dev”, “latest”, and “legacy”) together. No matter what version you are using, this migration is safe.

2. Add a X-Compatibility-Date header to all requests with a reasonable value (in the format YYYY-MM-DD; today’s date should suffice).

3. Test your changes (so you can let us know on Discord if any behavior changes).

4. Commit, deploy, enjoy.

Once we start introducing new routes, you simply bump your compatibility date and your application is ready for the new routes.

Best practices

• Always send a X-Compatibility-Date header with your requests.

  • If you can't, the compatibility_date query parameter is your friend.

• ESI will reject compatibility dates that are set in the future.

  • The date rolls over to the next day at downtime (11:00 UTC).

• You can check the X-Compatibility-Date response header to see what version your request was matched to. This is always your requested date or earlier, depending on the internals of the route.

Wrapping up

With this change, we simplify the ESI developer experience. On the EVE Online Discord there is a thread to discuss these changes, and we are looking forward to hearing your feedback on this.