Using the HTTP API¶

Kanzi Connect exposes access to service methods and data through stateless HTTP API. HTTP support is based on HTTP Virtual File service implemented as a core Kanzi Connect service.

Method invocations over HTTP require that the Kanzi Connect Server loads the service_ServiceInvoke library, which by default the server loads.

HTTP API is available through both GET and POST HTTP operations. When using POST, you must set the content type to

"application/x-www-form-urlencoded"

Querying service descriptions¶

You can query Kanzi Connect Server for the service descriptions in XML format. By default a service description contains only method and event definitions that do not refer to any custom types. To get all definitions, including custom types, include in the URL the details query parameter.

For example, to get in XML format the Content service description, use

http://localhost:8080/servicedescriptions/Content

For example, to get in XML format all definitions of the Content service description, use

http://localhost:8080/servicedescriptions/Content?details

Invoking service methods¶

You can invoke arbitrary local and remote service methods using a web browser. When you invoke a method, Kanzi Connect Server responds with a JSON document describing the result of the invocation, such as

{
    "status": "OK",
    "type": "bool",
    "value": "true"
}

For example, to start media playback for a few seconds, invoke the playTrack method in the Media service with playlistId and trackId named arguments

http://localhost:8080/serviceinvoke/Media/method/playTrack?playlistId=1001&trackId=1002

When you invoke the Media service with such URL, the playback stops automatically after a few seconds, because the Media service plays music only when at least one session exists for a service.

You can invoke the same method using a POST CURL command

curl.exe -X POST localhost:8080/serviceinvoke/Media/method/playTrack -H "Content-Type: application/x-www-form-urlencoded" -d "playlistId=1001&trackId=1002"

Querying service runtime data structure¶

You can query Kanzi Connect Server for the runtime data schema in XML format. For example, to get in XML format the runtime data schema for the Cluster service, use

http://localhost:8080/serviceruntimeschema/Cluster

Querying service runtime data values¶

You can query Kanzi Connect Server for the runtime data values for a service in JSON format. For example, to get in JSON format the current values of the Cluster service runtime data, use

http://localhost:8080/serviceruntimedata/Cluster

Kanzi Connect Server returns a JSON file that describes the current values of services runtime data, such as

{
 "state": {
  "rev":"1095536",
  "cli":"0"
 },
 "data": {
  "engine": {
   "speed":"171.802277",
   "rpm":"0",
   "power":"-0.357620",
   "gear":"0"
   }
 }
}

Where:

rev contains the data revision which increases by one for each update.
cli contains the value for the amount of clients listening to this runtime data.

Querying content provider structure¶

You can query Kanzi Connect Server for the structure of table-based content providers in XML format. For example, to get in XML format the structure of the information table for the service content provider at com.rightware domain, use

http://localhost:8080/contentproviderschema/com.rightware.service/information

Querying content provider data¶

You can query Kanzi Connect Server for table-based content provider data in JSON format. For example, to get in JSON format all data that is available in the songs table from the content content provider at com.rightware domain, use

http://localhost:8080/contentproviderdata/com.rightware.content/songs

With the SQLite content providers you can use additional variables to set the type of results you want to receive. For example, to get in JSON format only the first two songs sorted by the artist in ascending order, use

http://localhost:8080/contentproviderdata/com.rightware.content/songs?sort=artistasc&limit=2

You can use variables to filter the results.

Variable	Description	Availability
`columns`	Returns only the content from the columns you specify. For example, `columns=name,location` includes in the result only the `name` and `location` columns.	All table-based content providers.
`limit`	Limits the number of returned results from the results set. For example, `limit=2` returns only the first two results.	Only SQLite content providers.
`filter`	Filters the results based on the parameters you pass. For example, `filter=id=%3D1002` returns only the result where the `id` column has value 1002.	Only SQLite content providers.
`sort`	Sorts the results based on the parameters you pass. For example, `sort=artist+desc` returns results ordered by artist name in descending order.	Only SQLite content providers.