About
Download OpenAPI specification: [openapi.yml](openapi.yml) # Introduction Rudder exposes a REST API, enabling the user to interact with Rudder without using the webapp, for example in scripts or cronjobs. ## Versioning Each time the API is extended with new features (new functions, new parameters, new responses, ...), it will be assigned a new version number. 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, ...) or `latest`. You can change the version of the API used by setting it either within the url or in a header: * the URL: each URL is prefixed by its version id, like `/api/version/function`. ```bash # Version 10 curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/10/rules # Latest curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules # Wrong (not an integer) => 404 not found curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/3.14/rules ``` * the HTTP headers. You can add the **X-API-Version** header to your request. The value needs to be an integer or `latest`. ```bash # Version 10 curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 10" https://rudder.example.com/rudder/api/rules # Wrong => Error response indicating which versions are available curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 3.14" https://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 a safe period of time to allow migration from previous versions. Existing versions Version Rudder versions it appeared in Description 1 Never released (for internal use only) Experimental version 2 to 10 (deprecated) 4.3 and before These versions provided the core set of API features for rules, directives, nodes global parameters, change requests and compliance, rudder settings and system API 11 5.0 New system API (replacing old localhost v1 api): status, maintenance operations and server behavior 12 6.0 and 6.1 Node key management 13 6.2 Node status endpoint System health check System maintenance job to purge software [that endpoint was back-ported in 6.1] 14 7.0 Secret management Directive tree Improve techniques management Demote a relay 15 7.1 Package updates in nodes 16 7.2 Create node API included from plugin Configuration archive import/export ## Response format All responses from the API are in the JSON format. ```json { "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 (Success) code * __Error__ responses are sent with a HTTP error code (mostly 5xx...) ## HTTP method Rudder's REST API is based on the usage of [HTTP methods](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 existing objects (update a directive, reload a group, ...) ## Parameters ### General parameters Some parameters are available for almost all API functions. They will be described in this section. They must be part of the query and can't be submitted in a JSON form. #### Available for all requests Field Type Description prettify booleanoptional 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 unnecessary load on the server side. Default value: false #### Available for modification requests (PUT/POST/DELETE) Field Type Description reason stringoptional or required Set a message to explain the change. If you set the reason messages to be mandatory in the web interface, failing to supply this value will lead to an error. Default value: "" changeRequestName stringoptional Set the change request name, is used only if workflows are enabled. The default value depends on the function called Default value: A default string for each function changeRequestDescription stringoptional Set the change request description, is used only if workflows are enabled. Default value: "" ### Passing parameters Parameters to the API can be sent: * As part of the URL for resource identification * As data for POST/PUT requests * Directly in JSON format * As request arguments #### As part of the URL for resource identification Parameters in URLs are