API (JSON-RPC)

Via the programming interface (API) you can externally access your IT documentation. You can read, create, update and delete data -- the same functions as in the Web GUI, but fully automatable.

Technical background#

The i-doit API provides typical CRUD functionality. Data can be

• created (Create),
• read (Read),
• updated (Update) and
• be deleted (Delete).

A client (e.g. a script) sends a request to the server (i-doit) to execute a method (Remote Procedure Call). The result is returned as a response. The API uses the JSON-RPC protocol in version 2.0 over HTTP with JSON as the exchange format. Requests are sent via HTTP POST in JSON format, responses are also returned as JSON.

API calls can be made asynchronously without losing the context between requests and responses. The programming language used can be freely chosen.

Download#

The API is offered as a free add-on for download in the customer portal for the pro variant.

Configuration#

The API is configured via the Web GUI of i-doit, found under Administration → Add-ons → JSON-RPC API.

Please note that API request logging creates a file in the installation directory of i-doit under log/ for each request. This could lead to increased disk space usage with heavy API usage.

Access#

Access to the i-doit API is via a special URL. src/jsonrpc.php is appended to the base URL of the i-doit instance. Example: https://demo.i-doit.com/src/jsonrpc.php.

Authentication and authorization#

An API key is mandatory for processing requests through the API. This key is used to identify the tenant. Additionally, the use of a dedicated user account for authentication can be enabled, for which permissions can be assigned as usual. Using a dedicated user for each third-party system or script enables easy tracking of data flow. For a very large number of requests (thousands), it is recommended to use the API method idoit.login for one-time authentication. Otherwise, too many sessions may be created in a short time without being closed, which can cause i-doit to stop functioning. The default user for API actions is "Api System", which can be found under "Contacts → Persons" if no specific username/password is used. If this user is archived or deleted, the API can no longer be used without authentication. In the Zammad integration, the API token is stored in the settings, for example.

Request-Format (JSON-RPC)#

A request to the i-doit API is a JSON object with a specific structure that follows the JSON-RPC 2.0 standard. The essential fields are:

• "jsonrpc": A string specifying the version of the JSON-RPC protocol, typically "2.0".
• "method": A string containing the name of the method to be called (e.g. "cmdb.object.create").
• "params": A structured object or array containing the parameters to be passed to the method. This includes the "apikey" for authentication as well as method-specific parameters.
• "id": A unique identifier for the request, generated by the client. It can be a string, a number or null. The server uses this value to associate the response with the request. If id is null or missing, it is a notification for which no response is expected.

Example of a simple request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "jsonrpc": "2.0",
    "method": "cmdb.object.create",
    "params": {
        "type": "C__OBJTYPE__SERVER",
        "title": "My little server",
        "apikey": "c1ia5q"
    },
    "id": 1
}

Response-Format (JSON-RPC)#

The server's response to an API request is also a JSON object.

• "jsonrpc": String with the JSON-RPC protocol version ("2.0").
• "result": This field is present when the method has been executed successfully and contains the result of the method. The content is method-specific.
• "error": This field is present when an error has occurred during the processing of the request. It contains an error object (see Error handling section). Either "result" or "error" is present, but never both.
• "id": This value corresponds to the "id" value of the original request.

Example of a successful response:

1
2
3
4
5
6
7
8
9

{
    "jsonrpc": "2.0",
    "result": {
        "id": "3351",
        "message": "Object was successfully created",
        "success": true
    },
    "id": 1
}

Error handling (JSON-RPC)#

Error handling in JSON-RPC 2.0 is standardized. An error object within the response typically contains the following fields:

• "code": An integer indicating the error type.
  • defaultized codes include -32700 (Parse error), -32600 (Invalid Request), -32601 (Method not found), -32602 (Invalid params), -32603 (Internal error).
• "message": A short, concise string describing the error.
• "data" (optional): Additional application-specific information about the error.

In addition to standard JSON-RPC errors, i-doit can also return specific error messages. For example, errors such as "Usersettings are only available after logging in" or "Could not connect tenant database" are returned when the "Api System" user has been archived or deleted. The documentation for a new method should list all specific errors that this method can trigger.

Using the i-doit attribute documentation#

A helpful listing of all categories and attributes used in i-doit can be found in the administration:

i-doit provides an "Attribute documentation" that contains a listing of all categories and attributes as well as their expected data types. This is the authoritative source for understanding the data elements of the i-doit CMDB model, especially when parameters or response fields use i-doit-specific constants or property keys. For custom categories and attributes, the technical keys can be found directly in the i-doit web interface in the respective custom category.

Finding i-doit constants and property keys

This table serves as a guide for where to find the required identifiers and constants for API usage.

Endpoint Documentation v2#

Here you can find v2 API requests with their request types, response types, arguments and the form of the request.

Clients and Libraries#

There are already numerous projects and products that use the i-doit API. Here we present some clients and libraries:

Documentation for download (outdated)#

A documentation created by the developers is available for download in PDF format.

Since version 1.8.1, the API has been released as an add-on. Previous releases were included in i-doit.

FAQ#

Error Messages#

Releases#