New Implementation Best Practices

If you'd like to add a new exchange, broker, or market data provider to XChange, you've come to the right page. Here we outline the steps for creating a new implementation from the ground up. It's actually not too hard and there are already lots of examples to copy and paste from as you go.

Note: If you're using Eclipse, please import our code formatter here. If you're using IntelliJ, you can try using the Eclipse code formatter file with the Eclipse Code Formatter Plugin.

Please fork and develop on the "develop" branch!

Step 1

Familiarize yourself with the data provider's API. What data is provided? What API to they have? In which format is the data returned? Do you need a login or key? Are there limitations on how often you can query the data? Create a file called api-specification.txt and take some notes.

Step 2

Create a new Maven module for the data provider. Update the pom.xml file using existing pom.xml files as a template.

Step 3

Get actual data and store it in a file in the project under test/resources. For example, see example-ticker-data.json. You can use http://jsonformatter.curiousconcept.com/#jsonformatter to format it nice.

To get the raw JSON returned from an API endpoint through XChange you first need a logback.xml file on your classpath. You can find an example logback.xml file in the xchange-examples module here: https://github.com/timmolter/XChange/blob/develop/xchange-examples/src/main/resources/logback.xml. Make sure the following line is UNCOMMENTED:

<logger name="si.mazi.rescu" level="TRACE" />

You will then find the returned raw JSON logged to the console on the line beginning like this:

si.mazi.rescu.HttpTemplate - Response body: 

Step 4

For each data file, create a corresponding Java object (DTO) that will contain all the data in the file. You can use http://jsongen.byingtondesign.com/ to speed up the process. Oh and make it immutable (see BitstampTicker.java). There are examples of how to create DTOs that Jackson can unmarshall JSON into of varying complexity throughout the XChange project, so just look around for examples.

Step 5

Create JUnit tests to verify that the raw JSON to unmarshalled DTO works. See TickerJSONTest.java.

Step 6

Then you create an adapter class to take the provider-specific DTO (a raw DTO) and convert it into an XChange DTO. See BitstampAdapters.java.

And unit test that too (see BitstampAdapterTest.java)!

Step 7

Put in all together in two exchange service classes, such as BitstampMarketDataService.java and BitstampMarketDataServiceRaw.java. The *Raw class should fetch the JSON and deserialize it into exchange-specific DTOs. The non-*Raw class should use the *Raw class to get the exchange-specific DTOs and convert them to XChange-specific DTOs.

Step 8

In the module "xchange-examples", add example classes to demo the new exchange API capabilities. See TickerDemo.java.

Step 9

Submit a pull request against the develop branch.

A Note About Error Handling

The REST client that XChange uses (ResCU) provides a nice mechanism for handling returned JSON that has a different format than the expected valid JSON. See this Wiki page for more information.