REST API

The Splunk REST API is new for 3.0. It allows access to Splunk features from your custom application through a HTTP request. It returns an XML document that can be parsed for the desired information such as configuration values or search results. Splunk 3 uses a REST endpoint to communicate with its browser client. External developers can, and are encouraged to, use this service to integrate Splunk with existing infrastructure. REST is based on the standard HTTP protocol, making it accessible from any programming environment that supports HTTP requests.

The SOAP API from previous versions will continue to be supported for existing functionality until Splunk 3.1, but for new applications we encourage use of REST instead. Note that several features, such as user management, are not complete. For these functions, continue to use SOAP until they are available in the REST API. While calls to the SOAP and REST interfaces will not be directly compatible, for the remaining features there will be some commonality that is intended to ease the transition to REST. Also, an XML API will be available in a forthcoming release.

To see the endpoint reference, from a supported browser login to a 3.x Splunk server and then go to http://yourhost:8000/v3. This document contains a list of all valid endpoints along with documentation on required arguments and test forms to try various options. You can use the test forms to create sample requests to use as a model for accessing the API from your own application.

Note that v3/controlapi, direct access to all the methods in control_api and the Python Control Layer, is not intended for production use. The controlapi interface is expected to change frequently. You can enable or disable access to controlapi with enableRestControlApi in web.conf.

Messages

The REST API will return any messages (info, warnings, errors) in an 'messages' node. If there are no messages, then no node will appear. Your application should check for the presence of this node and handle accordingly. For example:

<envelope>
   <messages>
      <msg type="ERROR">The apikey is invalid</msg>
      <msg type="PERSISTENT">Your license has expired</msg>
      <msg type="INFO">Today is your lucky day</msg>
   </messages>
   <somethingElse>
   </somethingElse>
</envelope>

Possible message types are:

DEBUG -- low level debugging information
INFO -- messages from the server that usually indicate a change in state from normal operation
WARN -- messages indicating that something needs attention, but operation can continue
ERROR -- messages indicating that something was unexpected, and operation was aborted
PERSISTENT -- messages indicating things like license violations, disk space warnings, restart messages, and others that are handled by the Splunk UI differently

Authentication

Most requests require authentication. The standard authentication method is through the /auth/getToken method. Provide the username and password in the URL and then parse the returned XML document for the authToken element:

http://localhost:8000/v3/auth/getToken?usr=admin&pwd=changeme

<envelope>
  <authToken>f0913e8bf5c1c077df0cc18df21b1586</authToken>
</envelope>

The authToken string is then specified as an apikey argument in subsequent calls, like this:

http://localhost:8000/v3/alerts/get?id=34&apikey=f0913e8bf5c1c077df0cc18df21b1586

You can also authenticate from your browser with a valid login (a cookie containing your authToken is created with a port number to identify different Splunk instances, like "SPLUNK_SESSION_8000". When you login to Splunk from your browser and then go to v3, you are using the same session and do not need to specify an apikey argument.

Search

Construct a search request with a search string, output format and your authToken. Note that when you explicitly construct a search this way you have to provide terms that are normally handled for you in the Splunk UI, like "search". Also, whitespace and punctuation must be correctly encoded for use in a URI.

To get results from your search, pipe it to a command that formats it in the desired format, either outputxml outputraw, or outputcsv.

The search

http://localhost:8000/v3/splunk/search?q=search%20sudo%20guest%20%7C%20outputxml&apikey=2603471463dd923c4278607226070485

returns an XML document containing the results. For no results, it looks like this:

<envelope>
    <searchResults timestamp="07/03/2007:13:22:14">
<command>search sudo guest | outputxml</command>
<results type="empty"/>
</searchResults>
</envelope>

Enabling/disabling REST configuration options

Various options for the REST API can be controlled by the web.conf configuration file.

twistedLoginTimeout
timeout value for Twisted

restApiPostMode
Certain REST endpoint should be accessed via HTTP POST, instead of HTTP GET. By default, the REST endpoint will log a warning in the web_service.log whenever an endpoint that recommends a POST operation is accessed via GET. You can change this setting with restApiPostMode.

none = does not check; GET and POST are allowed
permissive = warns if REST method should be accessed via POST method
strict = throws error if POST-only REST method is accessed via GET

enableRestControlApi
true to enable the controlapi methods, default is false

Examples

The following Javascript excerpts are from an application that requests an auth token and then retrieves a list of the user's saved searches. Note that it is using XMLHttpRequest and parsing the returned document with standard XML DOM (Document Object Model) methods.

First, get a valid auth token:

var feedAuth = {url:"http://localhost:8000/v2/auth/getToken?usr=admin&pwd=changeme"};    

    xml_auth_request = new XMLHttpRequest();
    xml_auth_request.overrideMimeType("text/xml");
    xml_auth_request.open("GET", feedAuth.url, true);
    xml_auth_request.onreadystatechange=processRequest;    
    xml_auth_request.setRequestHeader("Cache-Control", "no-cache");
    xml_auth_request.send(null);

function processRequest()
{
    if(xml_auth_request.readyState==4)
    {
        if(xml_auth_request.status==200)
        {
            // 200 means we got a good response
            // extract auth token
            
            var doc = xml_auth_request.responseXML;
            var authTokenElements = doc.getElementsByTagName("authToken");

            // extract the auth token
            if (authTokenElements && authTokenElements.length) 
            {
                var authTokenItem = authTokenEls.item(0);
                if (authTokenItem.firstChild) 
                {
                    authToken = authTokenItem.firstChild.data;
                }
            }

With the auth token, you can use it to request the list of saved searches:

var feedSaved = {url:"http://localhost:8000/v2/saved/all"};        

            xml_request.open("GET", feedSaved.url + "?apikey=" + authToken);

Python example

Note Splunk requires a number of environment variables to be set, such as SPLUNK_HOME, and the correct PATH to be able to locate splunk files. Source the file setSplunkEnv in the splunk bin directory (usually /opt/bin/splunk) to set up the necessary environment. As long as the environment is correct, you can run your Python code from anywhere on your filesystem.

source /opt/splunk/bin/setSplunkEnv

import urllib as net
import xml.dom.minidom as xml

#
# set variables
#
endpoint = 'http://localhost:8000'
username = 'admin'
password = 'changeme'

mysearch = 'error'
numberOfResults = 5
outputAsCsv = False

# get authToken, via POST
# this makes a request to: http://localhost:8000/v3/auth/getToken?usr=admin&pwd=changeme
#
authMethod = endpoint + '/v3/auth/getToken'
authData = {'usr': username, 'pwd': password}
authResponse = net.urlopen(authMethod, net.urlencode(authData))
xmlDoc = xml.parse(authResponse)
tokenElements = xmlDoc.getElementsByTagName('authToken')
if not tokenElements:
    print 'No auth token found!'

authToken = tokenElements[0].firstChild.nodeValue
print 'Got authToken=%s' % authToken

# make search request, via GET
# this makes a request to: http://localhost:8000/v3/splunk/search?q=<mysearch>&apikey=<authToken>
#
searchMethod = endpoint + '/v3/splunk/search'
searchArgs = {
    'q': 'page 0-%d 50000 [search %s] | outputxml' % (numberOfResults, mysearch),
    'apikey': authToken
}
if outputAsCsv:
    searchArgs['clientformat'] = 'csv'

searchResponse = net.urlopen(searchMethod + '?' + net.urlencode(searchArgs))
print ''.join(searchResponse.readlines())

Previous: Scripting the Splunk search command | Next: SOAP API

Comments

No comments have been submitted.