API (JSON-RPC)

i-doit enables external access to the IT documentation via an application programming interface (API). With the API data can be read, created, updated and deleted. Thus the API offers similar functions like the Web GUI but the additional benefit is that you can automate them without any problems.

Technical Background#

The API of i-doitvides typical CRUD functionalities. With this, files can be

• Create
• Read
• Update and
• Delete.

For this, a client (for example, in the form of a script) sends a request to the server (i-doit) in order to execute a method on the server. This approach is called Remote Procedure Call (RPC). The result of the method is returned to the client as a response. In this communication the API of i-doit is based on the JSON-RPC protocol, version 2.0. HTTP is used as higher protocol and the JavaScript Object Notation (JSON) is used as exchange format. A request is send to the server in the JSON format per HTTP POST. The response is also made in JSON format.

API queries can take place in an asynchronous way without losing the relation between requests and responses. The utilized programming language can be chosen freely.

Download#

In the customer portal you can download the API for the pro version as add-on for free. Users of the open version can also download it for free via i-doit.org. The installation is in line with the same principles of other i-doit add-ons.

Configuration#

The API is configured via the Web GUI of i-doit and can be found at Administration → Interfaces / external data → JSON-RPC API.

Please note that the logging of API requests will create a file in the install path of i-doit at log/ for each request. This may lead to increased requirements of memory space in case the API is used intensively.

Access#

You can access the API of i-doit by activating a special URL. Add src/jsonrpc.php to the basic URL:

1

 https://demo.i-doit.com/src/jsonrpc.php

Authentication and Authorization#

An API key is required for requests to be processed by the API. The API key is used to identify the client. You can also activate the use of a dedicated user account for logging in. Rights can be assigned for this as usual. Otherwise, all rights are available via the API. An additional advantage is that you can specify a dedicated user for each third-party system/script in order to easily track which data flows from where to where.

Example#

With a simple example we create a new object of the type Server with the object title "My little server" via the API.

Request to server:

 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
}

Via cURL you can send this request for test purposes:

1
2
3
4

curl \
--data '{"jsonrpc":"2.0","method":"cmdb.object.create","params":{"type":"C__OBJTYPE__SERVER","title":"My little server","apikey":"c1ia5q"},"id":1}' \
--header "Content-Type: application/json" \
https://demo.i-doit.com/src/jsonrpc.php

Server response:

1
2
3
4
5
6
7
8
9

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

Attribute documentation#

A helpful listing of all categories and attributes used in i-doit is provided by a special URL:

For example, this listing shows you which name is used to access categories and attributes and which data types are expected by these attributes.
For custom categories or attributes, you will find the technical keys in the respective custom category. There it is possible to rename the technical keys.

Endpoint documentation v2#

Here you will find API requests with their request types, response types, arguments and request body shape

Clients and Libraries#

There are numerous projects and products applying the API by i-doit. We would like to introduce some clients and libraries:

Documentation for Download#

You can download a documentation maintained by the developers~ as PDF file. (out-dated)

Since version 1.8.1 the API is released as an add-on. Pre-releases were bundled with i-doit.

FAQ#

Error Messages#

Releases#