Extend Your Splunk App with Custom REST Endpoints

As you build more complicated Splunk apps, you might wonder, “What is the best way to make the features in my app more usable?”

If you’re adding new SPL commands or creating ways to input new data sources, the answer is straightforward. But imagine you’re trying to address one of the following scenarios:

• You want to perform complex setup processes or interact with services hosted outside of your end users’ Splunk software deployments.
• You want to streamline the bulk-update of knowledge objects in your app.
   

For cases like these, consider extending the Splunk REST API with custom endpoints. A custom REST endpoint is a developer-defined endpoint that lets you build out the Splunk REST API to meet your specific needs.

Note: You may have seen our new documentation about custom REST endpoints. Check out Extend the Splunk platform REST API with custom endpoints on the Splunk Developer Portal.

Two Great Uses for Custom REST Endpoints

So, what can you do with custom REST endpoints? Here are two great uses:

1. You want to introduce functionality into your app that the Splunk platform doesn't support natively.
   
   Say you want to make calls to a third-party service from your app. You can create a custom REST handler to interact with this service and then expose its endpoint to your users in Splunk Web. This process creates a seamless experience in your app’s user interface.
   
   Here are some example use cases for creating a custom REST endpoint to introduce new functionality into your app:
   
   • Sending information to or receiving information from an external service
   • Updating a lookup table using data from a remote service
   • Using a REST handler to perform background processes in your app
   
   
2. You want to manage your app’s custom configuration files.
   
   Say you routinely make a series of updates to multiple configuration files in your app. You can create a custom REST handler to bundle these changes into a single REST API request. This process is more reliable than performing the updates one by one through the browser.
   
   This blog post doesn’t cover creating a custom REST endpoint to manage your app’s configuration files. For more information about this use case, see Use the Extensible Administration Interface for custom REST endpoints on the Splunk Developer Portal.
    

How Custom REST Endpoints Work

When you make a request to an endpoint in the Splunk REST API, Splunk software routes your request to the REST handler defined in the restmap.conf file. To add a custom REST endpoint to this definition, create a restmap.conf file in your app that specifies the name and location of your endpoint. If you also want to make your endpoint accessible through the front end, create a web.conf file in your app to specify how to expose the endpoint in Splunk Web. 

Note that for Splunk Cloud Platform customers to access REST API endpoints, they need to submit a Support request. See Accessing the Splunk Cloud REST API in the Splunk Enterprise REST API Tutorials.

Create a Custom REST Endpoint

Now, let’s walk through how to create a custom REST endpoint. In this example, we’ll create a custom REST handler that returns the payload {"text":"Hello world!"}.

Step 1. Write the Python Script

First, we write the Python script for our custom REST handler, shown in the following image. We’ll save the script in the /bin directory of our app.

^{hello_world.py custom REST handler Python script}

In this example, we import the PersistentServerConnectionApplication base Python class, which is provided in Splunk Enterprise.

Then, we create the HelloWorld child class. This class contains the __init__ method to accept the self, _command_line, and _command_arg variables.

The HelloWorld class also contains the handle method, which takes in incoming request arguments through the in_string parameter and returns the {"text":"Hello world!"} payload when the endpoint is called.

Step 2. Map the Python Script to an Endpoint

After we write the Python script, we need to map the script to an endpoint. We can map our REST handler to an endpoint in our app’s restmap.conf file, as shown in the following image.

^{Script stanza in restmap.conf}

In this example, we create a script stanza and map this stanza to hello-world, the unique name associated with our custom REST handler.

Next, we specify other attributes for the REST handler. These attributes include the endpoint URI that the handler matches to, the script name, the script type, and the Python class that serves the API requests.

Step 3. Expose the Endpoint in Splunk Web

Now, we are ready to expose the endpoint on the Splunk Web server port. This step enables our users to call the endpoint in Splunk Web through an SPL search using the rest command. We can expose the endpoint in Splunk Web in our app’s web.conf file, depicted in the next image.

^{Expose stanza in web.conf}

In this example, we create an expose stanza and map this stanza to hello-world, the name associated with our endpoint. Note that the endpoint name is unique across all apps in your Splunk Enterprise deployment.

Then, we specify the URI where we mounted the endpoint in the restmap.conf file and the supported HTTP methods for our handler.

Now, our app’s end users can call this endpoint in the following ways:

• Using the rest SPL command as part of a search in Splunk Web.
• Using a command-line tool, such as cURL, to call the endpoint on the back-end management port.
   

What Now?

Now, you can try creating a custom REST endpoint for your own Splunk app!

See Use the script interface for custom REST endpoints on the Splunk Developer Portal for comprehensive documentation.

As always, if you have any questions or feedback, reach out at devfeedback@splunk.com.
 

Thank you to Amy Sutedja, Principal Software Engineer, for providing code samples.