Infoline IM web services documentation

Introduction

In order to allow access to Infoline data from your application, Infoline includes an API that exposes all in information that is accessible through the user interface. Through this interface you can add records, read information, update your assets, locations and all other entities.

Protocol

The web services to access Infoline IM are based on JSON-RPC version 2.0. However the following limitations apply:
  • Only named parameters are supported. Positional parameters are not allowed. Positional parameters imply tight coupling between the client and server application and would compromise future evolutions.
  • Batch requests are not supported in the current implementation. This may be added in the future.
A complete description of the JSON-RPC protocol is available at http://www.jsonrpc.org/specification The use of JSON-RPC has a number of advantages:
  • It is easy to write a JSON-RPC client in any computer language that includes a http client. You are not require to use a specific platform.
  • All modern languages include a JSON-RPC client or an open source implementation of if can be easily found on the web. In most cases you don't need to write protocol specific code.
  • The use of HTTP makes Infoline accessible from any place where you can access it using a web browser. No complex infrastructure to deploy
  • It is much more flexible than SOAP. You don't need to recompile your application when we add functionality to the service, thus allowing us to enrich the service as needed.

Request format

General JSON-RPC request

A JSON-RPC request looks like the following: 
{
  "method":  <name of the method invoked>,
  "id":      <Arbitrary request Id>,         // Required, but only really useful when using batch requests.
  "params":  { "p1" : "value 1",                   // The data needed by the request
               "p2" : "value 2",
               ......
               "pn" : "value n"
             }
}

Infoline request format

Infoline uses the general format. However, infoline expects some parameters to be present in order to respond properly.

Authentication

The credentials must be supplied as part of the "params" dictionary:
  • _uid: User login name
  • _pwd: User password. Note this is not your usual login password. To find it, go to Options / RFID App password. You can see the current password and have infoline re-generate a random password

Control flags

Some objects support flags that modify the behavior of 'Update' and 'Insert' functions. The flags need to be supplied as part of the "params" dictionary:
  • flg_novalidation: Causes the function to perform unconditionally without checking business rules. This can be useful if you are updating fields that don't have application rules and you want the update to always succeed, leaving other fields unchanged.
  • flg_nocascade: Do not cascade update to related items. (For example, do not update the components of a system.)
Both flags should be used with caution, only when absolutely necessary.

Methods and method specific parameters

Data access methods methods are named after the underlying data entity. Methods are provided to List, Read, Update, and Delete.

When updating, a parameter is required only for the fields to be updated. For example, to change the status of an asset, a typical request will be:

{
  "method":  "AssetUpdate",
  "id":      "1234",
  "params":  { "_uid": "mylogin",
               "_pwd": "mypassword",
               "id": 5861347,
               "status": "ACTIVE"
             }
}

Note the 2 "id" fields have 2 different meanings:

  • The first "id" is the arbitrary request id. Because batch requests are not supported, the value is not important. You may set it to a constant value
  • The second "id" field is the database ID of the asset you want to update. This ID is not visible in the use interface, however it is provided as part of the returned data when you do a list request

Data access methods naming conventions

Method names are made from the underlying data entity name and the desired type of operation.

Method name ::= <Entity><Action>

For example, the manipulation of the Asset object will be done though the following methods:

  • Assets: Returns the list of assets.
  • AssetRead: Returns all fields for a specific asset (Asset id must be provided).
  • AssetUpdate: Updates a specific asset (Asset id must be provided). The unchanged fields are not required.
  • AssetDelete: Deletes and asset.

Special parameters for list functions

The functions returning a list of items can use the following additional parameters:
  • _timeout: Set the database query timeout in seconds. The default is 30 which may be insufficient for complex queries.
  • _rowlimit: By default the total number of records is 50000. This preserves performance when when querying big lists.
  • _rangemin, _rangemax: For long lists, it may be userful to process it in chunks. You can use the _rangemin and _rangemax to specify the first and last row to be downloaded from the dataset. First row has index 0.
  • _output: To only return a subset of the available fields, you can specify the list of fields to return as an array of field names.
  • _filter: To select specific rows, you can specify key-value pairs of fieldname, value. Only rows matching the criteria will be returned. Values may include wildcard character *.
    • <
  • _ql: sets a pseudo-sql statement that will be applied to the resultset before sending to the client. This is the preferred way of specifying list of output fields. The syntax is similar to SQL, except the query does not contain a FROM clause, since the source table is always the base resultset.

Request examples:

Using _filter and _output 
{
	"_uid":		"mylogin",
	"_pwd":		"mypassword",
	"_rangemin":"0",
	"_rangemax":"4",
	"_filter": 	{ "Manufacturer":"Keysight*" },
  "_output": 	["manufacturer","manufmodelno","serialno"],
}
Using _ql 
{
	"_uid":		"mylogin",
	"_pwd":		"mypassword",
	"_rangemin":"0",
	"_rangemax":"4",
  "_ql":"select manufacturer, manufmodelno, serialno where Manufacturer like 'Keysight*' '"
}
Note the non standard wildcard character '*' instead of '%' which comes from the implementation of the LIKE operator in dotNet.

Data access methods security and safety

All data acces methods follow the same security and business rules as Infoline web application. This includes:

  • Data access authorization
  • Required fields
  • Cascade updates

For this reason you need to make sure to use a login name that has sufficent permissions to perform the operations.

© Keysight 2004-
Terms of use