ESI Tutorial: Using Swagger Codegen to Generate a Client API
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.
Here on this blog we regularly mention the fact that ESI uses a framework called Swagger. In fact, the word "Swagger" is directly in the name (EVE Swagger Interface)! We also regularly mention that Swagger provides the capability of auto generating code for the programming language of your choice. However, it's not entirely obvious from looking at Swagger documentation how one should go about generating and using a client library. This blog will cover two ways to generate a library using ESI with tools provided by Swagger.
Method 1: Using the Swagger Editor
Note: If you have problems using the Swagger Editor, look at this blog.
For those preferring UIs to bash, this is definitely the easiest way to go about library generation using Swagger. First, navigate to https://editor.swagger.io which will display an online editor window split into two panes. The pane on the left is for an OpenAPI specification while the pane on the right will show an interactive interface using that spec. Load up the ESI spec by clicking on the "File" drop down at the top and then clicking on "Import URL":
The latest versioned Swagger spec for ESI is available from the URL https://esi.tech.ccp.is/_latest/swagger.json. Drop the URL into the dialog that appears after clicking "Import URL" and the left pane will populate with the ESI Swagger spec. Look here for details on why the above URL is recommended.
Click on the "Generate Client" dropdown and, for the purpose of this tutorial, pick python (we all know flash is the best though /s).
This will download a zip file containing a generated client for Python. Extract this anywhere you would like so you can work with it.
Method 2: Curl'n It Up
Note: If you have problems using the Swagger Editor, look at this blog.
This method can only be used on Unix based systems and is for those wanting to automate all the things.
Swagger supplies an api that allows the programmatic generation of client libraries. The spec for the generator API itself (generated using Swagger of course) can be found at http://generator.swagger.io. The gist is this: send a POST request to the /gen/clients/{language} endpoint (replace {language} with the language of your choice) with a payload containing a URL pointing to the ESI Swagger spec. A curl command like the this will do the trick:
curl -X POST -H "Content-Type: application/json" -d '{"swaggerUrl":"https://esi.tech.ccp.is/_latest/swagger.json"}' "http://generator.swagger.io/api/gen/clients/python"
and the API will return a response that looks like
{
"code": "d40029be-eda6-4d62-b1ef-d05e2e91a72a",
"link": "http://generator.swagger.io:80/api/gen/download/d40029be-eda6-4d62-b1ef-d05e2e91a72a"
}
The link in the returned object can then be used to download a zipped client library with a tool like wget.
Using the Generated Python Client
In the terminal/command prompt navigate to the directory where you unzipped the python client. If the unzipped directory was not renamed, it should be called python-client. Create a python virtual environment using virtualenv with the command
virtualenv venv
and then activate the virtual environment:
For Unix based systems use source venv/bin/activate.
For Windows systems use venv\Scripts\activate.
Once inside the virtual environment, install the dependencies required for the Python client by running
pip install -r requirements.txt
requirements.txt can be found at the base of the python-client directory. To test it out, drop into a python shell by typing
python
then do the following:
import swagger_client
from swagger_client.rest import ApiException
api = swagger_client.CharacterApi()
api.api_client.set_default_header('User-Agent', 'my-test-agent') # Set a relevant user agent so we know which software is actually using ESI
api.api_client.host = "https://esi.tech.ccp.is" # see [1]
try:
response = api.get_characters_character_id(2112625428)
print(response)
except ApiException as e:
print("Exception when calling CharacterApi->get_characters_character_id: %s\n" % e)
If everything went as planned then the response should contain details about the character CCP Zoetrope.
To figure out how to call other ESI endpoints read python-client/README.md and look at the documentation in python-client/docs as it has code examples for calling every endpoint.
[1] This is needed to bypass an issue with Swagger code generation. The Swagger specification does not expect base paths that are a single forward slash "/", and the generated code currently contains an extra forward slash in the resulting full path. ESI uses strict URL matching, so this causes 404s. We will work with the Swagger community to fix this in the code generation stage if we can. For the time being this is a necessary step when using underscore routes.
Conclusion
As has been shown, it's relatively simple to get an auto generated ESI client library for most languages and frameworks. Simply pick the language you want to develop in, get generated ESI code using one of the methods above and get crackin' on that dream EVE Online flash plugin you've always wanted.
o7
- CCP Zoetrope
Appendix
The following paths have been added or updated in ESI since the previous blog:
- GET /latest/characters/{character_id}/industry/jobs (v1)
- GET /latest/characters/{character_id}/orders (v1)
- GET /latest/characters/{character_id}/blueprints (v1)
- GET /dev/dogma/effects/{effect_id} (v2)
Get a sneak peek about what's coming to ESI by watching this board.