REST/JSON services

iTop provides a REST/JSON interface which allows third party applications to remotely interact with iTop for retrieving, creating or updating iTop objects. This interface is based on a set of simple HTTP POST requests. The data passed to and retrieved from iTop are encoded in JSON using the UTF-8 character set.

Such requests can be performed from any programming language capable os issuing HTTP/POSTs and manipulating JSON encoded data. Requests can even be run directly in javascript inside any web page by the mean of cross-site scripting (iTop supports both CORS and JSON-P). An example of such cross-site scripting in javascript is given in the REST JSON Playground.

The URL to POST the requests looks like:

<itop-root>/webservices/rest.php?version=1.2

Such requests expect the following parameters to be passed:

• auth_user
• auth_pwd
• json_data

In fact, the HTTP method can be either POST or GET (this is needed for JSON-P support). POST and HTTPS are recommended for security reasons (to avoid passing the credentials in clear text) and also because GET imposes a limit on the size of the input data.

Let's have a look at all the parameters of this HTTP service:

These parameters apply to any type of operation that is requested.

The first operation you should be familiar with is: list_operations. This command returns the list of all possible operations.

The syntax of the json_data input is as simplest as could be:

{
   "operation": "list_operations"
}

The reply will look like:

{
   "version": "1.2",
   "operations":
   [
      {
         "verb": "core/create",
         "description": "Create an object",
         "extension": "CoreServices"
      },
      {
         "verb": "core/update",
         "description": "Update an object",
         "extension": "CoreServices"
      },
      {
         "verb": "core/get",
         "description": "Search for objects",
         "extension": "CoreServices"
      }
   ],
   "code": 0,
   "message": "Operations: 3"
}

Note that the part:

{
   "code": 0,
   "message": "Everything went well"
}

…is common to all the services delivered by rest.php, the other information returned depends on the requested operation.

The error codes are available in applicationextension.inc.php, as constants of the class RestResult:

The core service are generic services. They are the equivalent of the iTop Core PHP APIs: DBObject, DBObjectSearch and DBObjectSet.

Using this services, you can manipulate any kind of data, provided you know enough of the classes and their attributes.

A key is a mean to identify an object. This type of specification can be used to determine the target object for the operation, and it used to determine the value of a external key (or “foreign key”).

Three forms are allowed:

• Specify the id of the object (as a number):

...
   "key": 123

• Specify a search query (OQL):

...
   "key": "SELECT UserRequest WHERE caller_name LIKE \"monnet\""

• Specify search criteria (all criteria are combined with a AND operator):

...
   "key":
   {
      "name": "Monnet",
      "first_name": "Claude"
   }

The value of an attribute is given in a format which depends on the attribute type.

For most of the attribute types, the value is simply a scalar.

For the external keys, the value is a key (see definition above).

For Blobs (i.e. binary data), the value is given as an array of three items: data, filename and mimetype. The item 'data' is the binary data that has been base 64 encoded (see PHP/base64_encode)

For link sets, the value is an array of object definitions.

Here is an example that illustrates some cases:

   "name": "Monnet",
   "first_name": "Claude",
   "age": 80,
   "picture":
   {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAA8AAAAPCAIAAAC0tAIdAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACmSURBVChTfZHRDYMwDESzQ2fqhHx3C3ao+MkW/WlnaFxfzk7sEnE6JHJ+NgaKZN2zLHVN2ssfkae0Da7FQ5PRk/ve4Hcx19Ie6CEGuh/6vMgNhwanHVUNbt73lUDbYJ+6pg8b3+m2RehsVPdMXyvQY+OVkB+Rrv64lUjb3nq+aCA6v4leRqtfaIgimr53atBy9PlfUhoh3fFCNDmErv9FWR6ylBL5AREbmHBnFj5lAAAAAElFTkSuQmCC",
      "filename": "smiley.png",
      "mimetype": "image/png"
   {

The format for the response of core/… operations is the following:

{
  "objects":
  {
    "objectclass::objectkey":
    {
      ...
    }
  },
  "code": 0,
  "message": "Found: 1"
}

Where each object is the form:

    {
      "code": 0,
      "message": "",
      "class": "Person",
      "key": 1234,
      "fields": {
        "id": 1234,
        "name": "My last name",
        "status": "Active",
        "org_id": 123,
        .....
        .....
        .....
      }
    }

The list of attributes given can be controlled by the mean of the parameter output_fields (when available). The parameter output_fields can have the following forms:

• A list of attribute codes separated by a coma (e.g.: “name, status, org_id”). Only attributes of the queried class can be given here.
• * means all the attributes of the queried class
• *+ (since 2.0.3) means all the attributes of each object found (subclasses may have more attributes than the queried class)

Searches for a list of objects.

Example:

Passing the following json_data:

{
   "operation": "core/get",
   "class": "Person",
   "key": "SELECT Person WHERE email LIKE '%.com'",
   "output_fields": "friendlyname, email"
}

or, using another form of “key”:

{
   "operation": "core/get",
   "class": "Person",
   "key": 1,
   "output_fields": "*"
}

Creates a new object of the given class

Passing the following json_data:

{
   "operation": "core/create",
   "comment": "Synchronization from blah...",
   "class": "UserRequest",
   "output_fields": "id, friendlyname",
   "fields":
   {
      "org_id": "SELECT Organization WHERE name = \"Demo\"",
      "caller_id":
      {
         "name": "monet",
         "first_name": "claude",
      }
      "title": "Houston, got a problem!",
      "description": "The fridge is empty"
   }
}

… will result in a new User Request being created.

Some attributes have a special format:

• Link sets: only indirect link sets are currently supported, see the example given above
• Blobs: document contents (e.g. DocumentFile/file) must be in the form {data: base64-encoded-data, mimetype: …, filename: …}
• Case logs: three forms are allowed.
  • Passing a string is equivalent to adding a new message from within the GUI: the message is recorded on behalf of the current user (credentials used to invoke the web service).
  • Passing a structure in the form {add_item: {message: 'blah', user_id: 123, date:'2012-02-28 10:30'}} adds a single message too. user_id and date are optionals, defaulting respectively to the current user and the current date and time. Specifying user_id requires that the credentials used to invoke the service have Administrator rights, otherwise the operation would fail with UNAUTHORIZED error code.
  • Passing a structure in the form {items: [ {message: 'blah'} ]} sets the entire log.

Example of a response:

{
   "code": 0,
   "message": "",
   "objects":
   {
      "UserRequest::123":
      {
         "code": 0,
         "message": "created",
         "class": "UserRequest",
         "key": 29,
         "fields":
         {
            "id": 29,
            "friendlyname": "R-000029"
         }
      }
   }
}

Updates one object

Passing the following json_data:

{
   "operation": "core/update",
   "comment": "Synchronization from blah...",
   "class": "UserRequest",
   "key":
   {
      "description": "The fridge is empty"
   },
   "output_fields": "friendlyname, title, contact_list",
   "fields":
   {
      "contacts_list":
      [
         {
            "role": "pizza delivery",
            "contact_id":
            {
               "finalclass": "Person",
               "name": "monet",
               "first_name": "claude"
            }
         }
      ]
   }
}

… will update the User Request (identified by its description “The fridge is empty”) by setting the contact list to one contact (Claude Monet) and the role 'pizza delivery'.

"public_log": "blah blah blah",

"public_log": {
   "add_item":
   {
      "date": "yyyy-mm-dd hh:mm:ss",
      "user_login": "jfoo",
      "message": "blah blah blah",
   }
},

"public_log":
{
   "items":
   [
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "blah blah blah",
      },
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "blah blah blah",
      },
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "blah blah blah",
      }
  ]
},

Updates one object and applies a stimulus to change the state of the object

Passing the following json_data:

{
   "operation": "core/apply_stimulus",
   "comment": "Synchronization from blah...",
   "class": "UserRequest",
   "key": 15,
   "stimulus": "ev_assign",
   "output_fields": "friendlyname, title, status, contact_list",
   "fields":
   {
      "team_id": 18,
      "agent_id": 57
   }
}

… will update the User Request (identified by its key “15”) by setting the agent_id and team_id fields (which are mandatory for the state assigned) and then will apply the stimulus ev_assign that causes the ticket to transition from the state new to the state assigned.

Delete a set of objects

Passing the following json_data:

{
   "operation": "core/delete",
   "comment": "Cleanup for customer Demo",
   "class": "UserRequest",
   "key":
   {
      "org_id": 2
   },
   "simulate": false
}

… will delete User Request of the customer #2.

Each object reported has a deletion status code and a message giving additional information. The status codes are defined in core/restservices.class.inc.php, as constants of the class RestDelete:

Searches for related objects.

Given an object or a list of objects, searches for other objects that are impacting or impacted by those objects.

Passing the following json_data:

{
   "operation": "core/get_related",
   "class": "Server",
   "key": 1,
   "relation": "impacts",
   "depth": 4
}

… will search for all of the CIs that Server::1 does impact. The search depth is limited to 4 iterations (defaults to 20).

The results will be in the form:

{
   "objects":
   {
      "objectclass::objectkey":
      {
         ...
      }
   },
   "relations":
   {
      "origin-class::origin-key":
      [
         {
            "key": "destination-class::destination-key"
         }
      ]
   },
   "code": 0,
   "message": "Scope: 1; Found: Server=4, VirtualMachine=3, Farm=1"
}

Checks a user login + password.

Passing the following json_data:

{
   "operation": "core/check_credentials",
   "user": "john",
   "password": "abc123",
}

… will reply (if everything went well)…

{
   "code": 0,
   "message": "",
   "authorized": true,
}

If you have an iTop already installed (version 2.0.1+), then click here to test the REST API.

Here is the corresponding code: jsfiddle playground

It is possible to extend the services by developping a module (or extension) that declares a class (included in your custom module) implementing the interface iRestServiceProvider.

As soon as your module is installed, your custom services will be available and listed with operation=list_operations.