This module provides a servlet which exposes a conversion of the EVE Online Static Data Export (SDE). We use our own SDE library to provide access to a database version of the SDE as provided on Fuzzy Steve's site. The web service we expose is a REST API with Swagger annotations, which in turn makes it trivial to generate documentation and experiment with the API, as well as generate client libraries in various languages.
We maintain a public instance of the web service which usually exposes the last two SDE releases. To track changes between releases, we create a named release branch of this module corresponding to each SDE release. The master branch of this module normally corresponds to the latest SDE release. Each release of the web service corresponds to a named release branch of the SDE library which you'll also need in order to use this module.
The rest of this guide describes how to configure, build and deploy your own instance of this service.
The service expects you've already imported the SDE into your favorite database vendor. For the public site, we use MySQL, but for the code below you can use any JDBC and Hibernate friendly vendor.
You'll normally want to clone the branch of this module corresponding to the release you plan to use. If you're instantiating the service for an SDE release we don't support, then you'll need to determine whether there are any schema changes that aren't reflected in the code.
The SDE web service requires configuration for database and servlet settings. Since the SDE web service is normally built with Maven, configuration is handled by setting or overriding properties in your local Maven settings.xml file. The following configuration parameters should be set:
| Parameter | Meaning |
|---|---|
| enterprises.orbital.evekit.sde.ws.basepath | The base location where the servlet is hosted, e.g. http://localhost:8080 |
| enterprises.orbital.evekit.sde.ws.appname | Name of the servlet when deployed |
| enterprises.orbital.evekit.sde.jdbc.url | Hibernate JDBC connection URL for SDE instance |
| enterprises.orbital.evekit.sde.jdbc.user | Hibernate JDBC connection user name for SDE instance |
| enterprises.orbital.evekit.sde.jdbc.password | Hibernate JDBC connection password for SDE instance |
| enterprises.orbital.evekit.sde.jdbc.driver_class | Hibernate JDBC driver class name for SDE instance |
| enterprises.orbital.evekit.sde.jdbc.dialect_class | Hibernate dialect class name for SDE instance |
At build and deploy time, the parameters above are substituted into the following files:
- src/main/resources/META-INF/persistence.xml
- src/main/resources/SDE.properties
- src/main/webapp/WEB-INF/web.xml
If you are not using Maven to build, you'll need to substitute these settings manually.
We use Maven to build this module. We currently don't release this module to Maven Central but we may in the future. Therefore, you'll need to build it yourself. Note that the SDE library is not released either. You'll need to clone and build the SDE library first (and with matching version), before you attempt to build the SDE web service. A call to "mvn install" should build everything.
This project is designed to easily deploy in a standard Servlet container. Two parameters need to be substituted in the web.xml file in order for deployment to work correctly:
| Parameter | Meaning |
|---|---|
| enterprises.orbital.evekit.sde.ws.basepath | The base location where the servlet is hosted, e.g. http://localhost:8080 |
| enterprises.orbital.evekit.sde.ws.appname | Name of the servlet when deployed |
If you follow the configuration and build instructions above, these parameters will be substituted for you. These settings are used to define the base path for the REST API endpoints (via Swagger).
The default pom.xml in the project includes the Tomcat Maven plugin which makes it easy to deploy directly to a Tomcat instance. This is normally done by adding two stanzas to your settings.xml:
<servers>
<server>
<id>LocalTomcatServer</id>
<username>admin</username>
<password>password</password>
</server>
</servers>
<profiles>
<profile>
<id>LocalTomcat</id>
<properties>
<enterprises.orbital.evekit.sde.ws.tomcat.url>http://127.0.0.1:8080/manager/text</enterprises.orbital.evekit.sde.ws.tomcat.url>
<enterprises.orbital.evekit.sde.ws.tomcat.server>LocalTomcatServer</enterprises.orbital.evekit.sde.ws.tomcat.server>
<enterprises.orbital.evekit.sde.ws.tomcat.path>/sde</enterprises.orbital.evekit.sde.ws.tomcat.path>
</properties>
</profile>
</profiles>The first stanza specifies the management credentials for your Tomcat instance. The second stanza defines the properties needed to install into the server you just defined. With these settings, you can deploy to your Tomcat instance as follows (this example uses Tomcat 7):
mvn -P LocalTomcat tomcat7:deploy
If you've already deployed, use "redploy" instead. See the Tomcat Maven plugin documentation for more details on how the deployment plugin works. Note that the "path" Tomcat parameter should normally agree with "appname" as set in the configuration above.
The web page exposed by this module includes a link to the Swagger UI pre-populated with the correct swagger.json for your instance. This view will let you experiment with the web service via the Swagger UI. Use the Swagger Editor and import the swagger.json link (File->Import URL...) to generate a client in your language of choice.
Parameters for the SDE REST API methods follow the same general convention as the EveKit Model API. Every API method has at least two parameters:
- The continuation ID for paged results (contid). This value is used as a simple SQL offset into the paged results (minimum value capped at 0).
- The maximum number of results (maxresults) to be returned by the method.
Both parameters are optional with sensible defaults. Any remaining parameters are selectors on data fields stored in the SDE data. A selector is a JSON string which can be used to filter results according to the following syntax:
{any: <boolean>}Wildcard selector. If true, then this data field is not used to filter returned data. Setting this value to false has no effect.{like: <string>}String match selector. If the associated data field is string valued, then all returned data must satisfy the SQL expression 'field LIKE selector'. Normal SQL 'LIKE' syntax is allowed (e.g. % as wildcard).{values: [<v1>,...,<vn>]}Set selector. The associated data field of each returned data item must contain one of the listed values.{start: <lower>, end: <upper>}Range selector. The associated data field of each returned data item must satisfy lower <= value <= upper.
This syntax allows very flexible selection on SDE data. For example, to quickly find the inventory category for ships, set the categoryName selector to {like: "%Ship%" } on the inv/category endpoint. To find all types with "Raven" in the name, set typeName to {like: "%Raven%"} on the inv/type endpoint; and, to further restrict this set to those types actually on the market, set marketGroupID to {start: 0, end: 1000000}.
The SDE web service returns results in JSON format, for example:
[
{
"typeID": 17636,
"basePrice": 108750000,
"capacity": 625,
"chanceOfDuplicating": 0,
"description": "The Navy Issue Raven represents the best the Caldari have to offer on the battlefield: an all-out assault vessel with tremendous electronic warfare capabilities. Commissioned by Caldari Navy Special Operations Command in YC 104 in response to a campaign of coordinated Gurista attacks which threatened to decimate the populations of several planets in the Obe system, this hefty warship has since proven its worth many times over.",
"factionID": 500001,
"graphicID": 2123,
"groupID": 27,
"iconID": null,
"marketGroupID": 1379,
"mass": 97300000,
"portionSize": 1,
"published": 1,
"raceID": 1,
"radius": 250,
"soundID": 20068,
"typeName": "Raven Navy Issue",
"volume": 486000
}
]The fields are exactly those contained in the underlying SDE database. The SDE web service also returns data in the HTTP Response headers:
DateServer time when the result was returned (UTC).EveKit-SDE-VersionThe name of the SDE release for which results were returned.expiresThe date when the returned data will expire. Defaults to 24 hours for SDE results (since this are unchanged between releases).
The best place to get help is on the Orbital Forum.