ESI Quick Reference For New Developers
ESI Quick Reference For New Developers
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.
With the recent announcement that ESI has now reached parity with XML API and CREST there will undoubtedly be newcomers to ESI (welcome!). A lot of important information about ESI is strewn about in various blogs and may be overwhelming to newcomers. This blog will act as a quick reference for the most important things every new ESI developer should know listed all in one document.
What is ESI?
A RESTful API for EVE built using the OpenAPI 2.0 specification. Keep in mind OpenAPI used to be referred to as Swagger so any previous documentation will use that term.
Will ESI have account level info?
ESI is a character oriented API and will never have account level endpoints.
Is ESI rate limited?
No, but there is an error limit. As explained here and here if you generate 100 errors in a 60 second time window your applications will start receiving the HTTP status code 420 returned for every request it makes until the 60 second time window is done. For more info on how to watch for this read the previously linked blogs.
How does authentication work with ESI?
ESI authenticated routes can be accessed through EVE's SSO (single sign on). This previous blog takes you through a step by step process for authenticated calls.
Where is the documentation for ESI?
ESI's documentation sits in its code and is automatically generated using the OpenAPI specification. You can find a list of all available routes on the ESI Swagger UI found at https://esi.tech.ccp.is/. You can expand a given endpoint and see exactly what model it returns and even try out routes directly through the UI.
Is there any documentation showing ESI equivalent endpoints to XML API and CREST?
Why yes there is!
How does versioning work in ESI?
All routes released on ESI have numbered versions (e.g. v1, v2, v3) and are tagged with one of three labels: dev, latest and legacy. The following diagram is a good top level overview of the lifecycle of a route:
The short version: always use the versioned routes in your software, never use labels. Labels can change, versions do not.
How do you know if the versioned route you are using is deprecated?
Watch for the Warning HTTP header in all your calls, you will see something similar to Warning: 299 - This endpoint is deprecated. That means next time there is a version bump on that route then the version you are using will start 404'ing.
How do you automatically generate a client for ESI using OpenAPI?
You must use the JSON version of ESI's OpenAPI specification when generating a client. You can get the full specification for all routes categorized under each of the three labels legacy, dev, and latest at https://esi.tech.ccp.is/_<label>/swagger.json where <label> should be replaced with one of the three labels used in ESI. Notice the "_" before the label, this will make it so all the routes will have the version hardcoded into the URL rather than the label.
This is easier seen than explained, so to see what the previous paragraph means first go to https://esi.tech.ccp.is/latest/swagger.json and then visit https://esi.tech.ccp.is/_latest/swagger.json. Note the differences in URLs for the routes. Always use the "undescore" route.
A previous blog post gives detailed instructions for exactly how to generate a client library. Make sure to look at this blog if you run into problems.
How can you see differences between version's specifications?
We recently released a diff UI that will show you differences per route between two different versions.
How do I report a bug or ask for a new feature in ESI?
Make a new issue in our public GitHub repository.
How do I report a bug or ask for a new feature in SSO?
Make a new issue in our public SSO Github repository.
How can I keep up on new routes and features being released to ESI?
- First and foremost, watch our developer blog (which you're currently reading this on).
- Join our #esi slack channel.
- Watch the "ESI Deployment Timeline" Github project to see when new routes are released and when version bumps will happen.
- Watch our waffleboard to see the current progress of the issues submitted on our public GitHub repository.
When are CREST and XML API going away?
Can I help with ESI development?
The UI hosted on https://esi.tech.ccp.is is open sourced, so feel free to make that look better if you want! Here's a blog detailing how to run it locally. And as always your participation in our #esi slack channel helps inform us which directions to take ESI next.
o7
-- Team Tech Co.
Appendix
The following paths have been added or updated in ESI since the previous blog:
New routes:
- POST /latest/universe/ids/ (v1)
Promotions from dev to latest:
- GET /latest/alliances/{alliance_id}/ (v3)
- GET /latest/alliances/names/ (v2)
- GET /latest/characters/{character_id}/assets/ (v3)
- GET /latest/characters/{character_id}/clones/ (v3)
- GET /latest/characters/{character_id}/online/ (v2)
- GET /latest/characters/{character_id}/roles/ (v2)
- GET /latest/characters/{character_id}/search/ (v3)
- GET /latest/characters/{character_id}/skills/ (v4)
- GET /latest/characters/{character_id}/wallet/journal/ (v3)
- GET /latest/corporations/{corporation_id}/ (v4)
- GET /latest/corporations/{corporation_id}/assets/ (v2)
- GET /latest/corporations/{corporation_id}/members (v3)
- GET /latest/corporations/{corporation_id}/wallets/{division}/journal/ (v2)
- GET /latest/corporations/names/ (v2)
- GET /latest/search/ (v2)
- GET /latest/characters/{character_id}/stats/ (v2)
- POST /latest/characters/{character_id}/assets/locations/ (v2)
- POST /latest/characters/{character_id}/cspa/ (v4)
- POST /latest/corporations/{corporation_id}/assets/locations/ (v2)
- DELETE /latest/characters/{character_id}/contacts/ (v2)
Get a sneak peek at what's coming to ESI by watching our deployment timeline.
Migrating from the XML API? Find equivalent ESI endpoints to the XML API.
Migrating from CREST? Find Equivalent ESI endpoints to CREST.