How to access the ExtraHop REST API using Java

Although ExtraHop provides a powerful visualization system out of the box for viewing and analyzing your network traffic, you may need to retrieve your ExtraHop network data for integration into other systems. Perhaps you need device data for an overarching inventory management system. Or you may need specific application metrics for custom calculations involving other data sources. ExtraHop provides an extensive REST API for these purposes. It provides access to just about anything that you would want to know about your network. If you are looking to export a large amount of your network data in real-time, then you may want to opt for our Open Data Stream.

For this post, I'll show you how to use the ExtraHop REST API using Java. We will begin with retrieving active devices and finish up with an example involving metrics. The complete code for this post can be found at the ExtraHop GitHub repository. Feel free to reuse the code in your applications.

ExtraHop REST API and the REST API Explorer

The ExtraHop REST API is at http://<Your ExtraHop IP>/api/v1. Your code will use this as the base URI for API calls. As typical with REST, element URIs provide access to specific objects. HTTP methods such as POST and DELETE allow specific operations on these objects. For example to operate on devices, the URI to use is http://<Your ExtraHop IP>/api/v1/devices. You can find the full REST API documentation on our documentation site.

The ExtraHop REST API Explorer at http://<Your ExtraHop IP>/api/v1/explore is extremely valuable for testing. Here are some screenshots of how that looks and how to use it.

ExtraHop REST API Explorer

Expand an element to see the request and response details for an element URI. Send a request and check the response. To do this, we need to generate an API key first. This controls access to the REST API.

REST Element URI Details

If you don't already have an API key, you will need to generate a key in the ExtraHop Admin UI. Go to the API Access page and generate a new key. Keep this key handy. You will use this to test in the REST API Explorer and to access it in your code.

REST Element REST API Key

In the REST API Explorer, enter the API key at the top and use the Try it! button under the ExtraHop element to test it out.

Java REST API Client

I created a RestClient class to wrap access to the REST API. This allows instantiation of one object that manages all calls to the REST API. It wraps the element URI calls with methods that have the required REST API parameters. The class uses the Unirest library to simplify handling of the requests and responses. You can view the full source of the RestClient on the repo. I provided methods for several of the element URIs. To use the class, you just need the hostname or IP of your ExtraHop server and the API key. You can then start making calls. The following is a simple example of getting the ExtraHop platform and version information.

//create the client
RestClient restClient = new RestClient("10.7.65.54","dad42ec48c644983924d5c349406d99d");

//make calls to the REST API
String platform = restClient.getExtraHopVersion();
String version = restClient.getExtraHopVersion();

System.out.println("Platform:"+platform);
System.out.println("Version:"+version);

Query Devices

To query devices, you can make the following call.

Device[] activeDevices = restClient.getDevices(24);
System.out.println("Active devices in last 24 hours:\n");

//loop through and print each device
for(Device device:activeDevices)
System.out.println(device.toPrettyPrintString());

How did I get a Device object from the REST API? The ExtraHop REST API sends request and response data using JSON. This can be tedious to parse manually. Fortunately, Unirest allows JSON object mapping so that JSON is automatically converted to Java objects. To query devices, I created a Device class. The trick to mapping is naming the member variables according to the JSON format. This is documented in the REST API Explorer. The RestClient class then handles the conversion from JSON to the Device Object for you.

public class Device extends EHObject {

    private String node_id;
    private String extrahop_id;
    private String description="";
    private long user_mod_time=0;
    private long discover_time;
    private int vlanid=0;
    private int parent_id;
.
.
.

Querying Metrics

Querying metrics requires sending JSON data in the request to the REST API. This data specifies the query parameters. I wrapped this with the Metric class so that you just need to set the parameters on the object and it will be converted to JSON. But how do you determine what metric to query and how to define it? This is where the Metric Catalog can help. You can access the Metric Catalog from the ExtraHop Settings menu. From there, find the metric that you are interested in and then look at the REST API parameters section. Just set the Metric object accordingly.

ExtraHop REST API Parameters and Metric Catalog

The JSON response with the results data is converted to the MetricStats class. The following code sets the Metric object parameters, sends the query, and then simply prints the results in JSON format.

//create the metric query. use the Metric Catalog to find and set the parameters!
Metric metricQuery = new Metric();
metricQuery.setObject_type("application");
metricQuery.setMetric_category("http");
metricQuery.addSpec("name", "req");

//calls /metrics
MetricStats results = restClient.getMetrics(metricQuery);
//prints results in JSON format
System.out.println("getMetrics:"+results.toPrettyPrintString());

//calls /metrics/total
results = restClient.getMetricsTotal(metricQuery);
//prints results in JSON format
System.out.println("getMetricsTotal:"+results.toPrettyPrintString());

//calls /metrics/totalbyobject
results = restClient.getMetricsTotalByObject(metricQuery);
//prints results in JSON format
System.out.println("getMetricsTotalByObject:"+results.toPrettyPrintString());

Web App Example: HTML5 Charts and a Java Servlet

To showcase some of the things you can do with the REST API, I created a Java web application with HTML5 graphing using ChartJS and a Java servlet. This web application provides a request form that allows displaying of line and bar charts based on HTTP metric queries. The Java servlet makes calls to the ExtraHop REST API using the RestClient class and formats the response for the ChartJS graphs. The full web application source is available here. It is deployable on any servlet container like Tomcat.

The ExtraHop REST API is another example of the extensibility of the ExtraHop platform. It provides another way for you to access your network data. Combining it with the depth of features and cross-platform nature of Java and you have limitless possibilities for how you can use your data. Can't wait to see the cool applications you develop!