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.3

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.

Here is an example that illustrates some cases:

   "name": "Monnet",
   "first_name": "Claude",
   "age": 80,
   "picture": {
      "data": "iVBORw0KGgoAAAAN.......AAAAElFTkSuQmCC",
      "filename": "smiley.png",
      "mimetype": "image/png"
   }

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 text fields formatted as pure text, new lines are specified by the mean of “\”.

Example:

"name": "Monnet",
"description": "A famous french artist.\nLaunched the impressionism trend."
"presentation": "<p>A famous french artist</p><p>Launched the <em>impressionism</em> trend.</p>"
"age": 80,
"org_id": "SELECT Organization WHERE name = 'Demo'",
"location_id": 3,
"supervisor_id":
{
  "name": "Foo",
  "first_name": "John"
}

For Blobs (i.e. binary data), the value is given as an array of three items: data, filename and mimetype.

• 'data' is the binary data that has been base 64 encoded (see PHP/base64_encode)
• 'filename' is the name of the original file. Its purpose is provide a default file name in case the file gets further downloaded.
• 'mimetype' must match the format of the file so that iTop can display it correctly.

Example:

"picture": {
  "data": "iVBORw0KGgoAAAANSUhEUgAAAA8AAAAPCAIAAAC0tAIdAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACmSURBVChTfZHRDYMwDESzQ2fqhHx3C3ao+MkW/WlnaFxfzk7sEnE6JHJ+NgaKZN2zLHVN2ssfkae0Da7FQ5PRk/ve4Hcx19Ie6CEGuh/6vMgNhwanHVUNbt73lUDbYJ+6pg8b3+m2RehsVPdMXyvQY+OVkB+Rrv64lUjb3nq+aCA6v4leRqtfaIgimr53atBy9PlfUhoh3fFCNDmErv9FWR6ylBL5AREbmHBnFj5lAAAAAElFTkSuQmCC",
  "filename": "smiley.png",
  "mimetype": "image/png"
}

Since iTop 2.0.3, 3 syntaxes are possible for populating “CaseLog” fields: shorthand syntax, single item or whole log.

If a simple text string is supplied, the text will be added as a new entry in the case log with the current date & time and the current user, and the text will be implicitely considered as formatted in HTML.

Example:

"public_log": "blah blah blah",

If a structure with an entry named add_item is supplied, one can specify additional information:

• user name (defaults to the credentials used for the REST/JSON API)
• date/time of the entry (defaults to “now”)
• format of the comment (defaults to “html”, can be set to “text”)

Example:

"public_log": {
   "add_item":
   {
      "date": "yyyy-mm-dd hh:mm:ss",
      "user_login": "jfoo",
      "message": "The first line\nAnother line",
      "format":"text"
   }
},

If an array named items is suplied, the whole content of the case log will be replaced by the supplied entries.

Example:

"public_log":
{
   "items":
   [
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "<p>The first line</p><p>A second line</p>"
      },
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "<p>The first line</p><p>A second line</p>",
         "format": "html"
      },
      {
         "date": "yyyy-mm-dd hh:mm:ss",
         "user_login": "jfoo",
         "message": "blah blah blah",
         "format": "text"
      }
   ]
},

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

Example:

"contacts_list":
[
   {
      "role": "artist",
      "contact_id":
      {
         "finalclass": "Person",
         "name": "monet",
         "first_name": "claude"
      }
   },
   {
      "role": "Basket-ball",
      "contact_id": "SELECT Team WHERE name = 'San Antonio Spurs'"
   },
   {
      "contact_id": 1234
   }
]

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'.

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,
   "redundancy": true,
   "direction": "down"
}

… 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.