Skip to content

Latest commit

 

History

History
229 lines (157 loc) · 12.3 KB

introduction.md

File metadata and controls

229 lines (157 loc) · 12.3 KB
Raw

Introduction

In Rudder 2.7.0, a Rest API was added. This API allows you to interact with Rudder without using the webapp, for example via scripts or cronjobs.

## Authentication

To use the API, you need to be authenticated. Rudder may contain capital information about your IT, and we don't want that information to be public, do we?

Authentication is done via a dedicated API Account. Those accounts can be created in Rudder, on the 'API Accounts' page located inside the Administration part. API Accounts are not connected to standard user accounts, and are currently global, accessible by admins only.

Rudder API page

Once you have created an API Account, you can now use the API. A token is generated for each account which you will need to authenticate.

For any call to API, you will need to add a X-API-Token header to your request.

curl -X GET -H "X-API-Token: yourToken" http://rudder.example.com/rudder/api/2/rules

If you perform any action (Creation, Update, Deletion) using the API, the event log generated will record the API account as the actor.

## Versioning

Each time the API is extended with new features (new functions, new parameters, new responses, ...), we will increment the version number of the API. This will allow you to keep your existing scripts (based on previous behavior). Versions will always be integers (no 2.1 or 3.3, just 2, 3, 4, ...).

The initial REST API is numbered 2, to differentiate it with the partial API already avaiable. One notable exeception is the magic latest version, which will always point to the most recent version available (use at your own risk!) (note that this "magic" version is currently only supported in the URL access described below, not via the X-API-Version header - see http://www.rudder-project.org/redmine/issues/3817).

We added two ways to choose API version used:

  • By URL: each URL can be prefixed by the version you want to use, like /api/version/function.
# Version 2
curl -X GET -H "X-API-Token: yourToken" http://rudder.example.com/rudder/api/2/rules
# Latest
curl -X GET -H "X-API-Token: yourToken" http://rudder.example.com/rudder/api/latest/rules
# Wrong => 404 not found
curl -X GET -H "X-API-Token: yourToken" http://rudder.example.com/rudder/api/3.14/rules
  • By header. You can add the X-API-Version header to your request. The value needs to be an integer. If you use a wrong version you will get a message telling you which version is available
# Version 2
curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 2" http://rudder.example.com/rudder/api/rules
# Wrong => Error response indicating which version is available
curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 3.14" http://rudder.example.com/rudder/api/rules

In the future, we may declare some versions as deprecated, in order to remove them in a later version of Rudder, but we will never remove any versions without warning, or without leaving a significant period to allow time for migration.

## Response format

All responses from the API follow the same generic format. Both Errors and Success are based on the same model. All responses are in JSON format.

{
  "action": The name of the called function,
  "id": The ID of the element you want, if relevant,
  "result": The result of your action: success or error,
  "data": Only present if this is a success and depends on the function, it's usually a JSON object,
  "errorDetails": Only present if this is an error, it contains the error message
}
  • Success responses are sent with the 200 HTTP code
  • Error responses are sent with an Error HTTP code (mostly 5xx ...)
## HTTP method

Rudder's REST API is based on the usage of HTTP verbs (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html). We use them to indicate what action will be done by the request. Currently, we use four of them:

  • GET: search or retrieve information (get Rule Details, get a Group, ...)
  • PUT: add new objects (Create a Directive, Clone a Rule, ...)
  • DELETE: remove objects (Delete a Node, Delete a Parameter, ...)
  • POST: update exsiting objects (Update a Directive, Reload a Group, ...)
## Parameters

To use Rudder API, you will need to pass data to the API. Most of them depends on the called function and will be described below, in the corresponding function's section. Some exist for almost all functions and they are described here:

Passing parameters

Passing parameters to the API can take three forms:

  • As part of the URL
  • As request Parameters
  • Embedded in JSON

As part of the URL

Parameters in URLs are used to indicate which data you want to interact with. The function will not work if this data is missing.

# Get the Rule of ID "id"
curl -H "X-API-Token: yourToken" http://rudder.example.com/api/2/rules/id

Request parameters

In most cases, data will be sent using request parameters. for all data you want to change, you need to pass one parameter.

Parameters follow the following schema:

key=value

You can pass parameters by two means:

  • As URL parameters: At the end of your url, put a ? then your first parameter and then a & before next parameters
# Update the Rule 'id' with a new name, disabled, and setting it one directive 
curl -X POST -H "X-API-Token: yourToken"  http://rudder.example.com/api/rules/2/id?"displayName=my new name"&"enabled=false"&"directives=aDirectiveId"
  • As request data: You can pass those parameters in the request data, they won't figure in the URL, making it lighter to read, You can pass a file that contains data.
# Update the Rule 'id' with a new name, disabled, and setting it one directive (in file directive-info.json) 
curl -X POST -H "X-API-Token: yourToken" http://rudder.example.com/api/rules/2/id -d "displayName=my new name" -d "enabled=false" -d @directive-info.json

Embedded in JSON

Instead of passing parameters one by one, you pass only one JSON object containing all your datas. You'll also have to set the Content-Type header to application/json (without it the JSON content will be ignored).

Contrary to request parameters, datas needs to be typed: strings need quotes, booleans and integers don't.

The (prettified) format is:

{
  "key1": "value1",
  "key2": false,
  "key3": 42
}

Here is an example with an inlined data:

# Update the Rule 'id' with a new name, disabled, and setting it one directive 
curl -X POST -H "X-API-Token: yourToken" -H "Content-Type: application/json" http://rudder.example.com/api/rules/2/id -d '{ "displayName": "new name", "enabled": false, "directives": "directiveId"}'

You can also pass a file containing the JSON:

# Update the Rule 'id' with a new name, disabled, and setting it one directive 
curl -X POST -H "X-API-Token: yourToken" -H "Content-Type: application/json" http://rudder.example.com/api/rules/2/id -d @jsonParam

Note that some parameters cannot be passed in a JSON (general parameters, it will be precised when necessary), and you will need to pass them a URL parameters if you want them to be taken into account (you can't mix JSON and request parameters)

# Update the Rule 'id' with a new name, disabled, and setting it one directive with reason message "Reason used" 
curl -X POST -H "X-API-Token: yourToken" -H "Content-Type: application/json" "http://rudder.example.com/api/rules/2/id?reason=Reason used" -d @jsonParam -d "reason=Reason ignored"

General parameters

Some parameters are available for almost all API functions. They will be described in this section. All of them cannot be used in JSON parameters, and will need to be passed as request parameters

Available for all requests

				<tr>
					<td class="code">prettify <span class="label label-optional">Optional</span></td>
					<td>Boolean</td>
				<td>
				  Determine if the answer should be prettified (human friendly) or not. We recommend using this for debugging purposes, but not for general script usage as this does add some uncessary load on the server side.
					<p class="default-value">Default value: <code>false</code></p>
					
				</td>
				</tr>
		
			</tbody>
		</table>

Available for modification requests (PUT/POST/DELETE)

Field Type Description 
				<tr>
					<td class="code">reason <span class="label label-optional">See description </span></td>
					<td>String</td>
				<td>
				  Set the change message. If you set the reason message to be mandatory in /opt/rudder/etc/rudder-web.property (property rudder.ui.changeMessage.mandatory)
					<p class="default-value">Default value: <code>an empty string</code></p>
					
				</td>
				</tr>	

				<tr>
					<td class="code">changeRequestName <span class="label label-optional">Optional</span></td>
					<td>String</td>
				<td>
				  Set the change request name, won't be used if workflow are disabled. The default value depends on the function called
					<p class="default-value">Default value: <code>A default String for each function</code></p>
					
				</td>
				</tr>

				<tr>
					<td class="code">changeRequestDescription <span class="label label-optional">Optional </span></td>
					<td>String</td>
				<td>
				  Set the change request description, won't be used if workflow are disabled.
					<p class="default-value">Default value: <code>an empty string</code></p>
					
				</td>
				</tr>
		
			</tbody>
		</table>
Field Type Description