Splunk's REST API

REST is a programming method that provides simple access to Web-based resources. If you'd like to know more about REST methods, Wikipedia has an article on it titled Representational State Transfer.

Using REST Methods

HTTP has an uniform interface for accessing resources, which consists of URIs, methods, status codes, headers, and content distinguished by MIME type.

The most important HTTP methods are POST, GET, PUT and DELETE. These are often compared with the CREATE, READ, UPDATE, DELETE (CRUD) operations associated with database technologies.

The following table associates several common HTTP verbs with similar database operations, however the meaning of the HTTP verbs do not correspond directly with a single database operation. For example, an HTTP PUT is used to set the value of a resource and may result in either a creation or update as needed.

HTTP	CRUD
POST	Create, Update, Delete
GET	Read
PUT	Create, Update
DELETE	Delete

Splunk REST endpoint mappings

Starting in version 3.2, Splunk's REST endpoints are served via SSL off the splunkd process using the URL format: https://hostname:port/services/, where hostname is your Splunk server's hostname, and port is the port number on which the splunkd process is listening.

For example, if you are logged into the local machine and Splunk is running on the default ports, you can use https://localhost:8089/services/ to access the REST endpoints. Remember, your mileage may vary depending on the machine's hostname, ports, registered certificates, and firewall settings.

Note: All examples in this documentation assume you are logged into the local machine and that Splunk is running on the default ports

HTTP ports Splunk uses

Splunk listens on the following ports:

Splunk Web listens on port 8000 by default
splunkd listens on port 8089 by default

Connections to splunkd, splunkd are encrypted by default.

What you need to know about searching with Splunk

Before you can build effective extensions to Splunk using the REST API, you should understand some basics about how Splunk works. You're building queries, so you'll need to understand the Splunk search language. Splunk is an IT Data search engine. It allows you to index any format of IT data from any source in real time from all of your applications, servers, and devices, and then search, navigate, alert, and report on all this data in real time.

What's the data type that you're getting back?

might be search results, or events
might be timechart data

This is important because if you want to draw a graph, you'll want it run through the timechart operator.

How are you handling time ranges?

Time values are passed in as header parameters.
You can pass time values as starttime and endtime in epoch seconds (which you must do if you pass them this way), or you can pass them in the search string itself.
To see how that works, use Splunk Web to build queries. Try searching for something over a custom time range. If you go to the saved search window, you can copy in the query to use.
You can also specify times relative to "now". Here is the BNF for the relative time arguments:

<rel_time> ::= "now" | ("-"|"+")<integer><unit> <unit> ::= "s" | "m" | "h" | "d" | "w" | "m" | "y"

If "now" is given, the unadulterated result of a call to the system call "time" is returned. Otherwise, the current time is converted into a broken down time, and the specified quantity is subtracted or added from that component of the broken down time.
For example, suppose "now" is 10/9/2007, 07:32:15, the relative specifier "+2d" corresponds to 10/11/2007, 07:32:15.

What extracted fields are available for use in your query?

You should know what these are. Any fields that are extracted at search time are available. Be aware that when you search, multiple field extractions are being created and returned to the interface, although you may not see them all.

The following query gives you the number of occurrences and distinct values of each field in the most recent <maxresults> of sourcetype=foo
> sourcetype=foo | stats count(*) dc(*)

You can append | transpose to this search to make the output easier to read.
If you want this information over all results, perform the same search using the CLI dispatch command, which is useful for long-running searches.

Comments

No comments have been submitted.