Splunk REST API is EASY to use

If you are feeling adventurous and have a burning desire to try out Splunk’s REST API, look no further, this article demonstrates the first few basic steps to get you started. I am going to demonstrate how to create a search job and retrieve the search results with Splunk’s REST API using your preferred programming language (I am using Python in this article). I tested this code against Splunk 4.2.2

How do I get started?
There are basically 4 simple steps to create a search job and retrieve the search results with Splunk’s REST API and they are:

1. Get a session key
2. Create a search job
3. Get the search status
4. Get the search results

These steps are laid out as below:

Step 1: Get a session key
Use this REST endpoint ‘/services/auth/login’ to obtain a session key before you proceed to create a search job in Step 2. Use the POST method and include the username and password in the HTTP request body. A sample implementation in Python to get a session key with the ‘/services/auth/login’ REST endpoint is as follow:

import urllib
import httplib2
import time
import re
from time import localtime,strftime
from xml.dom import minidom
import json
baseurl = 'https://localhost:8089'
username = '<username>'
password = '<password>'
myhttp = httplib2.Http()

#Step 1: Get a session key
servercontent = myhttp.request(baseurl + '/services/auth/login', 'POST',
                            headers={}, body=urllib.urlencode({'username':username, 'password':password}))[1]
sessionkey = minidom.parseString(servercontent).getElementsByTagName('sessionKey')[0].childNodes[0].nodeValue
print "====>sessionkey:  %s  <====" % sessionkey

Step 2: Create a search job
Once you have obtained a session key from Step 1, you may create a search job. The REST endpoint that is used to create a search job is '/services/search/jobs'. Use the POST method and include the session key as 'Authorization' in the header and provide the search string in the request body. A search ID will be returned as a result.

#Step 2: Create a search job
searchquery = 'index="_internal" | head 10'
if not searchquery.startswith('search'):
searchquery = 'search ' + searchquery

searchjob = myhttp.request(baseurl + '/services/search/jobs','POST',
headers={'Authorization': 'Splunk %s' % sessionkey},body=urllib.urlencode({'search': searchquery}))[1]
sid = minidom.parseString(searchjob).getElementsByTagName('sid')[0].childNodes[0].nodeValue
print "====>sid:  %s  <====" % sid

Step 3: Get the search status
With the search ID that you obtained from Step 2, you may now perform a GET request against this endpoint '/services/search/jobs/<searchid>/' to determine if the search job is completed. It is simple to obtain the status of the search job and the sample implementation is as provided.

#Step 3: Get the search status
myhttp.add_credentials(username, password)
servicessearchstatusstr = '/services/search/jobs/%s/' % sid
isnotdone = True
while isnotdone:
    searchstatus = myhttp.request(baseurl + servicessearchstatusstr, 'GET')[1]
    isdonestatus = re.compile('isDone">(0|1)')
    isdonestatus = isdonestatus.search(searchstatus).groups()[0]
    if (isdonestatus == '1'):
        isnotdone = False
print "====>search status:  %s  <====" % isdonestatus

Step 4: Get the search results
Finally, once you have determined if the search job is completed from Step 3, you may now retrieve the search results. The results may be returned in JSON, XML or CSV. Use the GET argument 'output_mode' in the URL to retrieve the search results in different formats. Use 'count=0' to retrieve all search results based on your search string you provided in Step 2. Use this REST endpoint '/services/search/jobs/%s/result' to retrieve the search results. The GET arguments together with the REST endpoint should look like this '/services/search/jobs/<searchid>/results?output_mode=json&count=0'

#Step 4: Get the search results
services_search_results_str = '/services/search/jobs/%s/results?output_mode=json&count=0' % sid
searchresults = myhttp.request(baseurl + services_search_results_str, 'GET')[1]
print "====>search result:  [%s]  <====" % searchresults

Summary
I hope you find this article helpful and useful enough to get you started in developing your own applications using Splunk REST API. This is the complete implementation of the steps outlined from getting a session key to retrieving the search results.

import urllib
import httplib2
import time
import re
from time import localtime,strftime
from xml.dom import minidom
import json

baseurl = 'https://localhost:8089'
username = '<username>'
password = '<password>'

myhttp = httplib2.Http()

#Step 1: Get a session key
servercontent = myhttp.request(baseurl + '/services/auth/login', 'POST',
headers={}, body=urllib.urlencode({'username':username, 'password':password}))[1]
sessionkey = minidom.parseString(servercontent).getElementsByTagName('sessionKey')[0].childNodes[0].nodeValue
print "====>sessionkey:  %s  <====" % sessionkey

#Step 2: Create a search job
searchquery = 'index="_internal" | head 10'
if not searchquery.startswith('search'):
searchquery = 'search ' + searchquery

searchjob = myhttp.request(baseurl + '/services/search/jobs','POST',
headers={'Authorization': 'Splunk %s' % sessionkey},body=urllib.urlencode({'search': searchquery}))[1]
sid = minidom.parseString(searchjob).getElementsByTagName('sid')[0].childNodes[0].nodeValue
print "====>sid:  %s  <====" % sid

#Step 3: Get the search status
myhttp.add_credentials(username, password)
servicessearchstatusstr = '/services/search/jobs/%s/' % sid
isnotdone = True
while isnotdone:
    searchstatus = myhttp.request(baseurl + servicessearchstatusstr, 'GET')[1]
    isdonestatus = re.compile('isDone">(0|1)')
    isdonestatus = isdonestatus.search(searchstatus).groups()[0]
    if (isdonestatus == '1'):
        isnotdone = False
print "====>search status:  %s  <====" % isdonestatus

#Step 4: Get the search results
services_search_results_str = '/services/search/jobs/%s/results?output_mode=json&count=0' % sid
searchresults = myhttp.request(baseurl + services_search_results_str, 'GET')[1]
print "====>search result:  [%s]  <====" % searchresults

----------------------------------------------------
Thanks!
Nicholas Key