REST API Use Cases

The Graylog REST API provides the full functionality of the Graylog web UI. The REST API lets you automate frequently repeated processes and allows for integration with third-party applications.

You can access the REST API through the API browser, which is useful for simple, individual requests. However, for more advanced uses, you’ll need a programmatic approach that allows you to build workflows and repeat your processes as needed.

This article demonstrates how you can use the API browser as a starting point for building complex API requests, which you can incorporate within your chosen development environment.

Requirements

• Appropriate user credentials for your Graylog instance.

• (Recommended) An access token to avoid sending credentials as plain text. Admin users can create access tokens for themselves and other users. See REST API Access Tokens for complete information.

• A command-line interface (CLI) or scripting environment from which to run commands or API calls.

• Access to the API browser to discover available endpoints and methods. See API Browser for complete information.

Choose Your Tools

To get the full benefits of the REST API for automation and integration, you need to use some form of development tool to perform API calls. You might make requests from the command line with a tool such as curl. On the other hand, you could use a scripting or programming language. Some languages have the ability to make direct API calls while in others you can wrap a command-line call, such as a curl request, within your code.

You have many choices, and your specific use case as well as personal preference and experience will determine the best options for your environment.

Support from the API Browser

The use cases and examples below demonstrate how you can use the API browser to learn about the methods available to you in Graylog. These examples also show you how you can find required information for parameters.

The Graylog REST API includes more than 200 endpoints. Most endpoints include multiple methods (GET and POST, for example). Often endpoints have multiple commands for the same method type (like two or three different POST commands on an endpoint). Remember, any function you can perform through the Graylog web interface you can also perform through the API. In other words, the API provides a lot of functionality.

Use the API browser to familiarize yourself with the capabilities available through the API. and to learn parameters and syntax required for individual methods. For more information, see API Browser as well as the uses cases below.

Example Uses Cases

The Graylog REST API allows GET, POST, PUT, and DELETE methods. The use cases and code examples below demonstrate how to construct a variety of command line calls to the REST API by first finding endpoints and methods and their parameters through the API browser.

Example 1: Method Types

The following examples demonstrate how to construct basic GET, POST, and PUT requests on the command line using curl.

GET

The GET command is the most basic method you can run. The GET command retrieves or “gets” information from Graylog without modifying data or settings.

The GET command is a way to look at what is going on in your Graylog environment. It is also a useful method to find information you need for other commands.

The following GET command retrieves information about all nodes in the Graylog environment:

curl -u ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token -H "Accept: application/json" -X GET http://localhost:9000/api/cluster?pretty=true

In the above code, be sure to insert your own generated access token in place of the example shown.

The curl command provides all the required information as part of curl options. The following information is sent to the API through this command:

• -u: This option signals user authentication. Following security best practice, the authentication is done via a generated access token. See REST API Access Tokens for complete information.

  Hint: It is possible, though not recommended, to use a username and password for authentication instead of an access token: -u <username>:<password>.

• -H: This option is used to supply headers. This command includes the Accept header, which tells the API how the response should be formatted (in this case, as JSON data).

• -X: This option indicates the request (or command) type, as in this case the GET command.

• The URL: Although curl has a URL flag (--url), it is optional and typically omitted. The URL itself, however, is required, which consists of:

  • The access point for the API, host:port/api/.

  • The endpoint, cluster.

  • Finally, to return data in a more easily readable format, include the optional pretty=true parameter, appended with the ? character.

When you run this command, the JSON-formatted output provides general Graylog cluster information such as the following:

POST

The POST command allows you to tell Graylog to perform an action. Typically, actions include creating elements (new index sets or streams, for example) or triggering a job. POST commands usually require more options than GET commands.

The following POST example triggers a system job that scans every index and stores information about what indices contain messages and in what time ranges.

curl -u ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token -H "X-Requested-By: XMLHttpRequest" -X POST http://localhost:9000/api/system/indices/ranges/rebuild

In the above code, be sure to insert your own generated access token in place of the example shown.

In this example, the command provides the following information:

• -u: User authentication. See the GET command above for details.

• -H: This option is used to supply headers. This command includes the X-Requested-By header, which specifies the source of the request as required by non-GET commands.

  Warning: All non-GET API requests must include and set a value for the X-Requested-By header. This value is required to prevent cross-site request forgery (CSRF) attacks.

• -X: This option indicates the request (or command) type, as in this case the POST command.

• The URL: Although curl has a URL flag (--url), it is optional and typically omitted. The URL itself, however, is required, which consists of:

  • The access point for the API, host:port/api/.

  • The endpoint, system/indices/ranges/rebuild.

When you run the command, a 202 response code generally indicates that the command completed successfully.

PUT

The PUT command allows you to add or change data within Graylog. Use PUT commands to update information on existing elements, such as changing information or settings or adding additional information. PUT commands tend to be the most complicated, including multiple required or optional parameters.

The following example PUT command updates information on an existing index set:

curl -u ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Requested-By: XMLHttpRequest" -X PUT http://localhost:9000/api/system/indices/index_sets/66901b1e5449d50c06aab2b4?pretty=true -d '{"title": "BobsImportantSet", "description": "Important indices only Bob can use.", "shards": 1, "replicas": 0, "rotation_strategy_class": "org.graylog2.indexer.rotation.strategies.TimeBasedSizeOptimizingStrategy", "rotation_strategy": {"type": "org.graylog2.indexer.rotation.strategies.TimeBasedSizeOptimizingStrategyConfig", "index_lifetime_min": "P30D", "index_lifetime_max": "P40D"}, "retention_strategy_class": "org.graylog2.indexer.retention.strategies.DeletionRetentionStrategy", "retention_strategy": {"type": "org.graylog2.indexer.retention.strategies.DeletionRetentionStrategyConfig", "max_number_of_indices": 20}, "index_analyzer": "standard", "index_optimization_max_num_segments": 1, "index_optimization_disabled": false, "writable": true, "default": false, "field_type_refresh_interval": 60000}'

In the above code, be sure to insert your own generated access token in place of the example shown.

The following information is included in this PUT command:

• -u: The authentication information is identical to the previous two commands.

• -H: This option is used to supply headers. This command includes multiple headers:

  • The Accept header, which tells the API how the response should be formatted (in this case, as JSON data).

  • The Content-Type header, which tells the API the format of data you are sending with the command, JSON.

    Hint: The Content-Type header is often required on POST commands as well. If you are passing data in the request, this header is required.

  • The X-Requested-By header, which specifies the source of the request as required by non-GET commands.

    Warning: All non-GET API requests must include and set a value for the X-Requested-By header. This value is required to prevent cross-site request forgery (CSRF) attacks.

• -X: This option indicates the request (or command) type, as in this case the PUT command.

• The URL: Although curl has a URL flag (--url), it is optional and typically omitted. The URL itself, however, is required, which consists of:

  • The access point for the API, host:port/api/.

  • The endpoint, system/indices/index_sets/66901b1e5449d50c06aab2b4.

    Hint: Note that the endpoint includes the index set ID. To find this ID, run the GET system/indices/index_sets command either in the API browser or on the command line. The IDs for every index set are listed in the output.

  • The optional pretty=true parameter. The command outputs all the properties after the update so you can verify that settings have been changed and potentially do additional processing.

• -d: This option is used to provide data to the endpoint. Typically, this data is formatted as JSON, which is what the Content-Type header specifies. The Data Type Model in the API browser shows what properties are available to update. Any property you include in this data section replaces any previous value for that same property in your Graylog environment.

  To discover what data you can update as well as how to format it, your best resource is the method detail pane in the API browser. See the next section for details.

When you run the command, the output displays all the properties with their newly set values.

Build Your JSON Data

Both PUT and POST methods can take JSON data input to create or update various Graylog elements. Check the method detail pane in the API browser for specific methods to see what properties you can set or change.

In the Data Type section under Parameters, use the Model view to see what properties you can update, along with the data type the property expects (integer, string, or Boolean, for example). Use the Model Schema view to show the JSON format itself to help format the command.

Note that when you have a property with multiple settings (for example, rotation_strategy), additional curly braces are required in the JSON data section. Always be careful to match your opening and closing punctuation (braces, quotes).

When sending JSON data via the API, it can be useful to work from the JSON schema shown in the API browser. You can copy the schema from the Model Schema view either into the parameter entry field or to another editor, then update the properties you want to change.

After you have added your new information, delete from the schema any optional properties that you are not changing. Finally, you need to remove line breaks and extra spaces before adding your JSON data to your command.

Example 2: Build a Command from the API Browser

This example demonstrates how you can work with information from the API browser to build command-line API requests. The use case presented shows how to clone a stream.

Step 1: Get a List of Streams

In the API browser:

1. Go to Streams : Manage streams, then click List operations.

2. Open the detail pane for the GET method /streams.

3. Click Try it out!

When the request runs, output similar to the following is shown:

To create a curl command line request to get the same list of streams, use the information from the output:

curl -u 'ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token' -H 'Accept: application/json' -X GET http://localhost:9000/api/streams

In the above code, be sure to insert your own generated access token in place of the example shown.

In this example, the command provides the following information:

• -u: User authentication, provided by a generated access token. See REST API Access Token for information about creating tokens.

• -H: The Accept header. This setting corresponds to the Response Content Type field shown in the API browser screenshot above.

• -X: This option indicates the request (or command) type, in this case the GET command.

• The URL: Although curl has a URL flag (--url), it is optional and typically omitted. The URL itself, however, is required, which consists of:

  • The access point for the API: host:port (your base Graylog URL).

  • The endpoint, which is shown as the Request URL in the API browser output: /api/streams.

Step 2: Find Required Parameters

To clone a stream through the API, the stream ID and index set ID of the original stream are required parameters.

In the API browser, you can find this information in the output from the list streams command above. The field id shows the stream ID for a given steam, and the field index_set_id is the ID for the index set for that stream. Copy the IDs of the desired stream to the clipboard.

To parse the curl command result, you can pipe the result into a tool like jq for JSON processing. The following command returns the ID of a stream called Test Stream.

curl ... | jq -r '.streams[] | select(.title == "Test Stream") | .id'

Step 3: Clone the Stream

In the API browser:

1. Open the detail pane for the POST method /streams/{streamid}/clone.

2. Enter the stream ID to be cloned as well as the cloned stream’s details, including the previously copied index set ID.

   Hint: For help constructing the required JSON data in the API browser, see Build Your JSON Data.

3. Click Try it out! to clone the stream.

To clone the stream on the command line, construct a curl command with the same values as above:

curl -u 'ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Requested-By: cli' -X POST http://localhost:9000/api/streams/66959475448bbf340590f41e/clone -d '{"index_set_id": "669003d209edae4cef01cb64", "title": "Test Stream Clone", "description": "This is a clone."}'

In the above code, be sure to insert your own generated access token in place of the example shown.

In this example, the command provides the following information:

• -u: User authentication, provided by a generated access token. See REST API Access Token for information about creating tokens.

• -H: This option is used to supply headers. This command includes multiple headers:

  • The Accept header, which tells the API how the response should be formatted (in this case, as JSON data).

  • The Content-Type header, which tells the API the format of data you are sending with the command, JSON.

  • The X-Requested-By header, which specifies the source of the request as required by non-GET commands.

    Warning: All non-GET API requests must include and set a value for the X-Requested-By header. This value is required to prevent cross-site request forgery (CSRF) attacks.

• -d: The data option contains the data to be sent. In this example, the data is a JSON-formatted section that includes the index set ID, title, and description.

• -X: This option indicates the request (or command) type, as in this case the POST command.

• The URL: Although curl has a URL flag (--url), it is optional and typically omitted. The URL itself, however, is required, which consists of:

  • The access point for the API, host:port.

  • The endpoint, /api/streams/66959475448bbf340590f41e/clone.

    Hint: Note that the endpoint includes the stream ID. To find this ID, run the GET /stream command, either in the API browser or on the command line. The IDs for every stream are listed in the output.

In a bash script, the stream ID and index set ID would be replaced by the variables resolved in a previous step.