Manage Splunk via REST

Manage Splunk via REST

Note: . As of now, only the search and auth endpoints are fully supported and certified (and are described earlier in this chapter). You can access the endpoints for other functions -- managing configurations and objects, for example -- but these endpoints will not be officially supported by Splunk until a future release. As each endpoint is certified, we'll update this manual to give details about how to use it.

You can manage your Splunk configuration via REST endpoints. In fact, this is how the Manager interface of Splunk is built. You can access management endpoints directly by going to their URIs. For example, you can access data inputs by going to:

https://localhost:8089/services/data/inputs

(Replace with your Splunk host and port.)

How to get started

You can make requests to Splunk's API from a terminal or browser, or within any code. The examples in this manual use curl, but you can use wget, libcurl or any other method to GET and POST in your preferred language. The management endpoints also support PUT and DELETE. Use a GET request to retrieve information from a resource and a POST to update a resource. DELETE removes an entire resource while PUT updates an entire resource. You'll probably want some way to parse the XML responses, too. Your preferred coding language should include libraries to support making HTTP requests and parsing XML responses.

Use the REST API

The URIs for configuration endpoints are served off of https://localhost:8089/services/. Use your installation host name and management port -- by default, 8089. Note that Splunk's API is secure, so use HTTPS whenever you access any endpoints.

Each endpoint gives you access to a different area of Splunk. For example, use the data endpoint to manage inputs, outputs and indexes. Use the auth endpoint to authenticate, get a session key and interact with users and roles.

POST to an endpoint to update values or create a new configuration. For example, POST to the search endpoint to create a new search. GET from an endpoint to retrieve configurations or results. For example, GET from the search endpoint to retrieve search results.

To see a list of currently available generic endpoints, navigate to https://localhost:8089/services/ from your browser. Click any endpoint to see what endpoints are served. For example, if you click data you'll see specific types of data inputs, index configuration and output/forwarding configuration options. If you click the create link, you'll see what parameters you can pass to that endpoint in a POST request.

Once you know which endpoint you want to GET and POST to, send REST requests the same way you send any HTTP request. From the command line, for example, you can use wget or curl. You can also build requests into your code, be it Java, .NET, perl, PHP, Python, Ruby...Just send your HTTP request to any available Splunk endpoint the way you'd handle any HTTP request.

Authentication

Before you can interact with Splunk's endpoints, you'll need to authenticate. You can authenticate in your requests by using HTTP auth with curl. For example:

curl -u admin:changeme -k https://localhost:8089/services/

Note that you'll have to change the host/port and username/password to your own installation specifics.

This example just returns an XML list of all the available endpoints.

If you're going to send multiple requests, you'll want to generate an auth token for your entire session. Learn more about how to get an auth token.

Parsing responses

Splunk's REST API returns HTTP response code and results in XML (unless otherwise specified). The HTTP response code indicates whether you were successful (200) or whether something went wrong with your request (400, 500). The Python library that is shipped with Splunk includes lxml and ElementTree to parse XML responses.

Splunk returns XML responses as either ATOM feed or generic XML.

A generic response looks like:

<response>
<sessionKey>30774f9d502004b5c655c08b5362bdca</sessionKey>
</response>

An ATOM response looks like:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>services</title>
  <id>https://localhost:8089/services/</id>
  <updated>2008-01-31T19:15:37-0600</updated>
  <generator version="31749"/>
  <author>
    <name>Splunk</name>
  </author>
  <entry>
    <title>streams</title>
    <id>https://localhost:8089/services/streams</id>
    <updated>2008-01-31T19:15:37-0600</updated>
    <link href="https://localhost:8089/services/streams" rel="alternate"/>
  </entry>
...
...
</feed>

Splunk's built in Python libraries support getting elements from the XML response. Most XML available XML parsing libraries offer support for this, as well. For example, use XPath (supported in JavaScript, Java and C#).

• Was this topic useful?
• Post a comment