Breadcrumbs

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-doit provides typical CRUD functionalities. With this, files can be

Created

Read

Updated and

Deleted.

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.

API instead of database

It's strongly recommended to prefer the API to database manipulations at all times. SQL statements bypass all sorts of internal processes. If a data record is manipulated via SQL per INSERT, UPDATE or DELETE, this could risk data integrity and could even disable i-doit.

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:

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

Authentication and Authorization

You need an API key so that requests will be processed by the API. Additionally, you can activate the function that a dedicated user account is activated for log-in. Permissions for this account can be set as usual. Otherwise all permissions are available through the API. Another advantage is the fact that a dedicated user can be set per third-party system/ script; this makes it easier to keep track of the data flow.

It may prove useful to use the API method idoit.login for a single authentication if a lot of requests (meaning thousands) are sent from a client. Otherwise it is possible that too many sessions are created in a very small time frame but are not terminated. This could result in the fact that i-doit stops working until the sessions have been terminated.