Contents


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

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.

Methods

Please see this article for detailled information about each method.

MethodDescription
idoit.versionDisplay the version of i-doit
idoit.loginLogin
idoit.logoutLogout
idoit.constantsQuery constants
idoit.searchSearch in i-doit
cmdb.objectsRead objects
cmdb.object.{create, read, update, delete}Create, read, update, archive an object, mark as deleted or delete an object irrevocably
cmdb.object_typesQuery object types
cmdb.category_infoRead the attributes of a category
cmdb.category.{create, read, update, delete}Create, read, update, delete a category entry
cmdb.dialog.{create, read}
Create or read the values of a dialogue field
cmdb.reportsExecute a report
cmdb.objects_by_relationRead objects by relation type
cmdb.location_treeRead location path
cmdb.workstation_componentsRead workstation components
cmdb.object_type_categoriesRead which categories are configured to which object types
cmdb.object_type_groupsRead which object types are assigned to which object type groups
cmdb.logbook.{create, read}Create, read logbook entry
cmdb.impact

Recursive query of all object relations

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:

 


{
    "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:

 


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:

 


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


 

Categories in the IT Documentation

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

https://demo.i-doit.com/index.php?load=api_properties

For example, this listing shows you which name is used to access categories and attributes and which data types are expected by these attributes.

Clients and Libraries

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

Feedback

Should a client or a library be missing in this article, we appreciate a short message to feedback@i-doit.com.

Documentation for Download

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

Releases

VersionDateChangelog
1.10.32019-05-06
[Bug] Assignment of devices to segments in slots not possible

[Bug] Validating requests breaks altering attributes
1.10.22019-04-01
[Bug] cmdb.category.read: Read entries by state "normal" unless otherwise noted

[Bug] Select value in a dialog+ attribute by its constant

[Bug] Fix SQL error when linking two connectors

[Bug] Object deletion with provided status (C__RECORD_STATUS__DELETED) will result in an infinite loop

[Bug] object state is mandatory although it should be optional

[Bug] idoit.license.read: Response in new format

[Bug] idoit.license.read: Use new license form

[Bug] Deleting an unknown entry ID results in success

[Bug] Create objects with defined SYSID via API

[Bug] API does not return all IP addresses of the IP list

[Bug] Read data from the drive category

[Bug] Purge assigned Groups via API

[Bug] Revert changes of the "salutation" property
1.10.12019-01-23
[Bug] Authentication with LDAP not possible
[Bug] SQL injection vulnerability during login
1.102018-12-17
[Improvement] Enable validation of API requests via expert setting
[Improvement] Do not allow different API keys within a batch request
[Improvement] Throw error when same ID is used within a batch request
[Improvement] API Key is required, user credentials are optional but include rights management
[Improvement] Create or update category entries with cmdb.category.save
[Improvement] Read licence information via API
[Improvement] Human-readable internal logging
[Improvement] Filter category entries by status
[Improvement] Recycle category entry
[Improvement] Purge category entry
[Improvement] Delete category entry
[Improvement] Archive category entry
[Improvement] Mark object as mass change template
[Improvement] Mark object as template
[Improvement] Recylce object
[Improvement] Purge object
[Improvement] Delete object
[Improvement] Archive object
[Improvement] Create object with category entries
[Improvement] Read objects with category entries
[Improvement] Do not return integer value as string in a response anymore
[Improvement] Describe in the Web GUI handling with categories and attributes
[Improvement] Call console commands via API
[Improvement] Fetch information about installed add-ons
[Improvement] Read all constants
[Improvement] Create, read, update and delete template objects and mass change template objects
[Change] cmdb.category.create and .update are deprecated
[Bug] cmdb.category.create: Unable to add license key to category "software assignment"
[Bug] Category "managed devices" returned wrong values
[Bug] cmdb.category.read: Wrong object relations and duplicates in category "C__CATS_NET_TYPE__IPV4"
[Bug] API delivers a null array with no assignment for key zone, but an object with an assignment
[Bug] Unknown attributes will be ignoriert
[Bug] Invalid values do not throw exception
[Bug] Server does not send notifcation for request without an "id"
[Bug] cmdb.category.read returns entries for empty categories
[Bug]
[Bug] Cables remain unused when connections are created with the API
[Bug] Application priority is not being saved
[Bug] API: Timeout is not being reset after every request
[Bug] Error when editing manfactor/model via API
[Bug] API: Fibre connections cannot be read
[Bug] When givin an ID as string it is possible that the resulting data will be wrong
[Bug] Connecting ports with the API uses wrong objects as cables
1.9.12018-04-16
[Bug]           cmdb.reports.read throws SQL error for variable reports
[Bug]           Method cmdb.reports throws PHP warning
[Bug]           After creating an object, a reindex is substantial to find an object via the search
[Bug]           Unable to create entries in category C__CATS__ORGANIZATION_CONTACT_ASSIGNMENT
[Bug]           API ignores language parameter
1.92018-01-23
[Improvement]   Searching for objects by attributes and values
[Improvement]   Enforce user rights for API calls
[Improvement]   Create object via "cmdb.object.create" with optional template
[Bug]           Unable to upload file
[Bug]           Logbook title is empty when saving a custom category
[Bug]           User-defined dialog plus contents select via API
[Bug]           Unable to read passwords
[Bug]           Method 'cmdb.object.create' creates object id's partly as string, partly as integer
[Bug]           Database error when trying to delete an object, which does not exist anymore, via the API
[Bug]           Dialog Plus fields that have a dependency on another attribute have not been created.
1.8.12017-03-02
[Bug]           Self-defined Dialog+ fields won't be displayed after creating them
[Bug]           Created dialog entries receive status 1 instead of 2 (normal)
[Bug]           cmdb.object.delete ignores parameter "status"
[Bug]           cmdb.category.create throws database error for category "model"

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