Interact with objects via REST

Interact with objects via REST

Note that, while this feature is available in Splunk 4.1, the endpoints have not been certified and will not be supported until they are.

Objects are configurations within Splunk that are scoped to users and apps. For example, saved searches, event types and fields are objects. Access objects from within a namespace -- specifying the app and user associated with the object.

How to get started

You can make requests to Splunk's API from a terminal or browser, or within any code. The examples here use curl, but you can use wget, libcurl or any other method to GET and POST in your preferred language. 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 object endpoints are served off of https://localhost:8089/servicesNS/<user>/<app>. 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, the saved endpoint gives you access to saved searches and event types. POST to an endpoint to update values or create a new object. For example, POST to the https://localhost:8089/services/saved/searches/ endpoint to create a new saved search. GET from an endpoint to retrieve configurations or results. For example, GET from the https://localhost:8089/services/saved/searches/<saved_search_name> endpoint to retrieve information for the given saved search.

To see a list of currently available object endpoints for your user, within your app, navigate to https://localhost:8089/servicesNS/<user>/<app>/. For example, https://localhost:8089/servicesNS/admin/search/saved/searches/.

Click any endpoint to see what endpoints are served. For example, if you click saved you'll see all the saved searches you've created. If you click the create link, you'll see what parameters you can pass to that endpoint in a POST request to create a new saved search.

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 returns an XML list of the endpoints for top level services.

If you're going to send multiple requests, 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 specific 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