By Splunk March 03, 2008
Update: Splunk now has a dedicated developer site that has API and SDK docs and examples (for version 4).
Splunk 3.2 is available for download! This release is one of our biggest so far, representing a tremendous amount of effort by our engineering team, and is a product that I’m proud to stand behind. As I mentioned in my last post about our push for the Splunk Platform, a central tenet is to make a compelling product that developers will not only understand, but also enjoy using. While Dr. LogLogic rambles on about how catering to developers sucks, we know that developers are a huge part of our user base (drop by the #splunk channel on EFNet sometime) and we will continue to make Splunk as flexible and extensible as possible.
With 3.2, we have begun moving some of Splunk’s core services over to a proper REST API. Now, for those of you who have already been using the REST API in 3.1, the new API in 3.2 and beyond is distinctly different, and is intended to replace any older versions. Therefore, the REST API of version 3.1 and before will now be referred to as the UI API, and the term “REST API” will refer to the new API that I’m covering in this post.
Before I dive into the details though, I’d like to clarify the usage of “REST” and what I mean when I speak of it. First of all, REST is not a protocol or standard. There is no RFC, or ISO specification on what constitutes REST; it is a philosophy about the relationship between entities in a software system and the interface to interact with those entities. Roy Fielding’s original thesis named it Representational State Transfer, which when put into practice means that URIs should convey meaning in a durable manner. In essence, REST emphasizes the “what” of a system rather than the “how”. In comparison, SOAP interfaces are based on codified standards that dictate the communication protocol. Lots more information on REST can be found on Wikipedia or in book form as RESTful Web Services
The New Search API
Splunk’s new search interface allows for multiple searches to be scheduled concurrently, and for the results to be retrieved asynchronously. Assuming that you’ve installed Splunk using the default settings, you can see all of your search jobs by pointing your browser to:
https://localhost:8089/services/search/jobs
This returns an Atom feed of all the search jobs present in the server. Each job has an ID, and so the URI for the Atom entry of a search job of ID=1234 can be found at:
https://localhost:8089/services/search/jobs/1234
Following that RESTian schema, each facet of a search job can be found as a sub-endpoint as well. For instance, the events, results, timeline, and summary data for each search can be found at:
https://localhost:8089/services/search/jobs/1234/events
https://localhost:8089/services/search/jobs/1234/results
https://localhost:8089/services/search/jobs/1234/timeline
https://localhost:8089/services/search/jobs/1234/summary
Each of those endpoints returns data in XML format by default, but can be switched over to JSON or raw text format.
The key to implementing a successful REST API lies in using the HTTP protocol to its fullest potential. Instead of adding a new search via something like /search/add_search, we simply POST to the parent /services/search/jobs endpoint. Instead of adding an extra /search/delete_search endpoint to delete a job, you issue an HTTP DELETE command directly on the /services/search/jobs/1234 endpoint. By treating each endpoint as a direct entity mapping, we simplify comprehension and dramatically reduce the total number of discrete endpoints.
The configuration API
The same model applies to our configuration system as well. Splunk stores its configuration in conf-style text files, using traditional stanza-separate key/value pairs. For example, the server.conf looks like:
[httpServer]
atomFeedStylesheet = /static/atom.xsl
max-age = 3600
follow-symlinks = false
To access this file from the API, you would first browse to:
https://localhost:8089/services/properties/server
This endpoint returns an Atom feed of all of the stanzas contained in the file. To view all of the key/value pairs in the [httpServer] stanza, browse to:
https://localhost:8089/services/properties/server/httpServer
To read a single key value like max-age, browse to:
https://localhost:8089/services/properties/server/httpServer/max-age
To change that value, issue an HTTP PUT to the same endpoint. To add a new key, issue a POST to the stanza-level endpoint, or issue a PUT directly onto the new key name.
The advantages of exposing everything via HTTP are obvious when it comes to integration and remote management. Every modern programming environment speaks HTTP, which means you can programmatically interact with Splunk from wherever you want. Everyone also uses a web browser, which means that probing the API is as easy as browsing the web.
Even with a simple API, there’s no reason for developers to recreate a language-specific library to access Splunk so we’re working on releasing a few downloadable libraries for use in Python, .NET, Java, and Perl. Check the Splunk Labs page for more information about those.