REST API Overview

The Splunk REST API

An API (Application Programming Interface) is a set of defined interfaces to accomplish a task, such as retrieving or modifying data. In Splunk's case, we provide an API method for every feature in our product. Programmers can use our API to make applications, phone apps, widgets, and other projects that interact with Splunk. Programs talk to the Splunk API over HTTP , the same protocol that your web browser uses to interact with web pages, and conforms to the principles of Representational State Transfer (REST).

There are two broad categories of tasks you can do with Splunk's REST API: run searches and manage Splunk configurations and objects. The REST API is divided into endpoints, or URIs served by the Splunk server (splunkd). All management endpoints behave the same, meaning they take the same global parameters and return responses in the same format. The search endpoints are special cases and behave differently from the configuration endpoints.

Since Splunk's API is REST, it supports GET, POST, and DELETE requests. Use a GET request to retrieve information from a resource and a POST to update an entity. DELETE removes an entity. After receiving your request, Splunk's API sends back an HTTP code an a response in XML (unless otherwise specified). If you're not familiar with REST or HTTP, we suggest you check out the Wikipedia articles on Representational State Transfer and Hypertext Transfer Protocol.

You can make requests to Splunk's API from a terminal or browser, or within any code. The examples in these tutorials 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.

There are two ways to access management endpoints, depending on whether you'll be working with an object or a configuration. Objects are configurations within Splunk that are scoped to users and apps. For example, saved searches, event types and fields are objects. Indexes, inputs, users and roles are configurations. Access objects from within a namespace -- specifying the app and user associated with the object. Access configurations directly.

Common HTTP Status Codes

For all requests to the REST endpoints, the HTTP server will return one of following status codes. See the reference docs for each particular endpoint to know which status codes it's capable of returning, so your code can handle all contingencies.

Authentication Methods

There are two methods of authenticating with the Splunkd HTTP server.

• HTTP Header -- Splunkd supports token-based authentication via the standard HTTPAuthorization header. This is the recommended method for most programmatic accesses against the API.
  1. Obtain a session key via the /services/auth/login endpoint, i.e.71e2f3553ba1dd279e36a6920a1e7840.
  2. Insert the session key into the Authorization header of every subsequent request, as follows:
     Authorization: Splunk 71e2f3553ba1dd279e36a6920a1e7840
• HTTP Basic -- Splunkd supports basic access authentication, as defined by RFC 1945. This is the method that is invoked when you browse the HTTP server from a web browser.

Global pagination and filtering

All endpoints that return lists of objects adhere to a standard interface for paging and filtering of their list output.

Request

Any endpoint that returns a list of objects in an Atom feed format provides paging and filtering capabilities via these params:

Response

Endpoints that return Atom feeds will convey pagination information via the OpenSearch extension to Atom. Additions to the standard Atom feed XML are:

• Opensearch namespace declaration
• totalResults node
• startIndex node
• itemsPerPage node

// sample response to request to saved searches: /services/saved/searches?offset=12&count=34
// the server has a total 765 saved searches

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:s='http://dev.splunk.com/ns/rest'>
      xmlns:opensearch='http://a9.com/-/spec/opensearch/1.1/'>
    <title>Indexes</title>
    <id>https://127.0.0.1:23424/services/data/indexes</id>
    <opensearch:totalResults>765</opensearch:totalResults>
    <opensearch:startIndex>12</opensearch:startIndex>
    <opensearch:itemsPerPage>34</opensearch:itemsPerPage>
    ....
</feed>

Object Sharing and Permissions

All endpoints that list user objects support object sharing and Access Control List (ACL) presentation and mutation. An ACL consists of the following fields:

A request to modify the ACL of an object should POST on the 'acl' custom action of an object (url: ...endpoint/entity-name/acl). The entire ACL should be provided rather than a diff. The following parameters should be provided: