Skip to content

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-doit provides 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.

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.

Configuration

Info

Removing HTML tags from description fields is only possible at i-doit version 1.15.2 with API version 1.11.3 installed.

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#

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.

The default user used for API actions is "Api System". This can be found under "Contacts -> People" if required.
This is only used if no username/password is used to connect to the API interface.
If the person is archived/deleted the API can no longer be used without authentication.

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
    },
}

Categories in the IT Documentation#

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

Categories in the IT Documentation

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.

Clients and Libraries#

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

Name Website Programming language License
Idoit.API.Client https://github.com/OKT90/Idoit.API.Client C# MIT
i-doit API client https://github.com/bheisig/i-doit-api-client-php PHP AGPLv3
i-doit CLI https://github.com/bheisig/i-doit-cli PHP AGPLv3
i-doit-go-api https://github.com/cseeger-epages/i-doit-go-api Go GPLv3
i-doit-python https://github.com/ScaleUp-Technologies/i-doit-python Python MIT
ansible-i-doit https://github.com/ScaleUp-Technologies/ansible-i-doit Python MIT
i-doit_API https://github.com/mvorl/i-doit_API Python AGPLv3

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)

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

FAQ#

Error Messages#

Error Message Problem
Usersettings are only available after logging in. (i-doit <= 21) Api System Person is archived or deleted.
Solution is to recycle the Api System user or to use a authentication method
i-doit system error: Could not connect tenant database. (i-doit >=22) Api System Person is archived or deleted.
Solution is to recycle the Api System user or to use a authentication method

Releases#

Version Date Changelog
2.0 2024-04-10 [Task] Implement base architecture for new endpoint "cmdb.external"
[Task] Restructure API, implement 'v2' endpoint
[Bug] Reading dialog+ entries from C__CATS__GROUP_TYPE leads to PHP error
[Bug] Inputs are not displayed as they were entered when reading via the API
[Bug] Categories and attributes needs to be updated
1.16 2024-02-27 [Bug] Dialog plus entry is not resolved via string
[Bug] cmdb.reports.read attaches " " to each value
[Bug] Reading a object via cmdb.object.read results in "0" for status and cmdb_status
[Bug] API System setting overwrites tenant setting
[Bug] PHP error when reading category C__CATG_GENERAL
[Bug] cmdb.logbook.create with using a string for alert_level the field is empty
[Bug] cmdb.logbook.create with using a interger for source will cause a php error
[Bug] cmdb.object.purge does not work because it checks quickpurge option
[Bug] cmdb.object_types filter for title/titles needs to be a constant
[Bug] Save buttons do not display a success notification
[Bug] "cmdb.objects.read" endpoint does not work correctly with "type_title" filter and limit
[Bug] When using cmdb.dialog.read for category = C__CATG__CLUSTER_ROOT and property = quorum, one level too much is output
1.15 2023-11-07 [Bug] Using API after update to i-doit pro 25 displays license error message
[Bug] Positioning an object in a rack misinterprets the rack unit position
[Bug] The new cryptography method significantly extends API equests when no login has occurred previously
[Bug] The overview of the API categories and attributes also shows virtual properties
[Bug] Operating system > Version cannot be referenced via title, if a second operating system has the ame version title
[Bug] Cannot create a dialog entry with value "0"
[Bug] API Categories and attributes not working
[Bug] C__CATG__NETWORK_PORT attribute default_vlan is not saveable
1.14.1 2023-06-13 [Task] Use 'cmdb.quickpurge' setting from tenant-settings
[Bug] Specific sub-categories can not be read via cmdb.objects.read
[Bug] Wrong successful message when using id instead of assigned_object
[Bug] The "Date for Notification" field in category "SIM" can not be emptied by the API
[Bug] Category Application is not displayed in Categories and attributes
[Bug] Set a Location in Rack is not correct if the Height unit sorting is Ascending
[Bug] Validaton error for custom category field time
[Bug] It is not possible to remove a Network -> Port -> addresses value
[Bug] It is not possible to assign a Host address -> assigned_port value
[Bug] Write data to Network > logical Ports > ports display SQL error message
[Bug] Layer 2 Net -> Assigned logical ports is not Editable
[Bug] Version of software assignment does not get assigned correctly
[Bug] "Categories and attributes" contains empty categories like Document and Floorplan
[Bug] Typo in response message idoit.logout
1.14 2023-03-21 [Improvement] New method "cmdb.ip_search.getNetworksByIp" returns all Layer3 obejcts a given IP is within the defined range (contributed by becon GmbH)
[Bug] Creating objects results in two entries in category 'Accounting'
[Bug] Category 'C__CATS__ORGANIZATION_CONTACT_ASSIGNMENT' can not be updated
[Bug] Translations for 'LC__CMDB__CATG__VD__HOST_RAID_ARRAY' is missing
[Bug] Add 'limit' and 'offset' options to endpoint 'cmdb.reports.read'
[Bug] SQL error when updating category 'network > port'
[Bug] Can't read type of layer2 net category
[Bug] Attribute "GPS" in category "C__CATG__LOCATION" is not writeable
1.13.1 2023-01-24 [Bug] Some fields are not being validated
[Bug] The Login method can use old session keys
[Bug] Validation error f_popup_
[Bug] Setting a Dialog Attribute via causes Fatal error
[Bug] Failed validation breaks the response
[Bug] installDate is always set to actual date/time
[Bug] The addresses attribute of the Network > Port category is incorrectly validated by API validation
[Bug] Date of Change is not altered when archiving a object via API
1.13 2022-09-05 [Task] PHP 8.0 compatibility
[Bug] Reports displayed via the API show language constants
[Bug] The Hostname field of the Monitoring category is incorrectly validated by API validation
[Bug] Changing the object type via the API via type: dialog constant is not possible
[Bug] An EntryID is needed to purge single-value entries
[Bug] The API shall be able to change passwords of users
[Bug] The Host address field of the Network > Port category is incorrectly validated by API validation
[Bug] The Latitude, Longitude and Position fields in the Location category cabinet are incorrectly validated by API validation
[Bug] The Type and Assigned license key fields of the Software Assignment category are incorrectly validated by API validation
[Bug] The Image attribute of the Object picture category is incorrectly validated by API validation
1.12.3 2022-02-21 [Bug] Edit host address > primary_fqdn sets field default gateway for the network to Yes
[Bug] If you edit an entry in the host address category, the IP address is removed.
1.12.2 2021-08-09 [Improvement] New parameters "offset" and "limit" for the "cmdb.category.read" method
[Bug] Virtual Switches > Creating Port Groups generates SQL error message
[Bug] Cluster members cannot be assigned via API using the category C__CATG__CLUSTER_MEMBERSHIPS
[Bug] The API can not create sub-categories in 'cmdb.object.create' context
[Bug] Layer 3 nets cannot be assigned with API validation enabled in Layer 2 nets
[Bug] When the layer 3 net is changed the layer 3 net is assigned to itself under layer 2 net assignment
[Bug] The category SLA (C__CATG__SLA) cannot be described via the API / With API validation switched off the category is emptied
[Bug] Dialog+ fields with 'PropertyFactory' definition can not be written
1.12.1 2021-01-18 [Bug] cmdb.category.quickpurge cannot be used with custom categories
[Bug] API version 1.12 can no longer be used in the open variant of i-doit
1.12 2021-01-14 [Bug] API: It is not possible to create a volume license via the API if "type": "volume license" is used
[Bug] Saving the "Layer-2 Nets" category deletes ip helper
[Bug] Contact assignment of a group of people will be deleted if it is updated via the API
1.11.3 2020-12-01 [Bug] Assign cable with fibers/leads while saving connection
[Bug] Limit assignment categories to one entry while creating
[Bug] Do not connect root location while creating cluster membership
[Bug] Do not create wrong output after removing cable connection
[Bug] Cannot assign objects to category "locally assigned objects" (requires i-doit 1.15.1)
[Bug] The category C__CATG__IMAGE is not read correctly via the API
[Bug] The category C__CATG__IMAGE cannot be written correctly
[Bug] The dates of the category contract information cannot be set via the API
[Bug] Category > Assigned Subscriptions C__CATG__ASSIGNED_SUBSCRIPTIONS key uuid cannot be set via string only via int
[Bug] Read Methods: Do not output HTML tags in description fields
[Bug] Objects can only be created via the API if the right to all object types is granted
[Bug] Ports cannot be uniquely referenced via the API
[Bug] Empty string supplied via API
1.11.2 2020-06-24 [Bug] API method: cmdb.object overrides the rights system
1.11.1 2020-04-09 [Bug] Updates via the API (save method) sets arbitrary entries in the Virtual Host category
1.11 2020-03-23 [Bug] Do not connect root location while creating cluster membership
[Bug] Objects that are changed via the API should also be locked for this period (Read > Update).
[Bug] Permission system error when using a user to change user-defined categories
[Bug] Data record of the standard_gateway always shows an ID
[Bug] When updating the category 'General' all tags are removed
[Bug] Report displays HTML in the result
1.10.4 2019-09-02 [Improvement] Add RPC to handle the CMDB status
[Improvement] Filling virtual custom category properties results in an error
[Improvement] Create, read, update and delete template objects and mass change template objects
[Bug] In the "Local Mass Storage" category, models cannot be created using the API.
[Bug] When updating the model, a Dialog+ value is created / displayed with the ID of the model.
[Bug] Update of a CPU title changes the frequency
[Bug] Improved handling of sorting of hight units when using API
[Bug] API "Categories and properties" page displays no content
[Bug] Saving the WAN category writes wrong values for router and net
[Bug] No salutation returns wrong value in JSON-API
[Bug] Missing values in the API method "cmdb.category_info"
1.10.3 2019-05-06 [Bug] Assignment of devices to segments in slots not possible
[Bug] Validating requests breaks altering attributes
1.10.2 2019-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.1 2019-01-23 [Bug] Authentication with LDAP not possible
[Bug] SQL injection vulnerability during login
1.10 2018-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.1 2018-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.9 2018-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.1 2017-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"