Deprecated - Using the HTTP API¶
Note
This topic describes Kanzi Connect HTTP API that still exists in the current version of Kanzi Connect, but is deprecated. Use the new HTTP API instead. See Using the HTTP API.
Kanzi Connect exposes most of its services also through the HTTP interface. You can invoke methods and receive events throught the Kanzi Connect HTTP API.
The main Kanzi Connect services using HTTP are:
Virtual File Service. See Virtual File Service.
Runtime data service. See Using service runtime data.
The Kanzi Connect HTTP API consists of:
GET¶
GET request format¶
The GET request format is
$http.get(URI)
where URI is for content requests
"/RestServices/content/" + <data domain> + ":" + <data fields> + "?" <clientId> + "&" +<sessionId>
where:
<data domain>sets the data domain within a service.<data fields>is a list of queried fields in the data domain separated by commas.<clientId>is an optional identifier of the client context within Kanzi Connect Server.To minimize Kanzi Connect Server resource use, initiate new clients only when you need them. The identifier is included in each successful response from the server. Inactive clients are purged after three seconds of inactivity. Trying to access a client that has been closed returns “400 Bad Request”.
<sessionId>is optional and you can use it instead of a URI path once a session is initiated. The identifier is included in each successful response from the server.
For events the notation is
"/RestServices "?" <clientId> + "&" +<sessionId>
In order to GET Kanzi Connect events, there must existing session running for a service. At least the client identifier is mandatory, but it is recommended to have the session identifier too.
When you reference the URI in the context of a web page on Kanzi Connect Server, you can leave out the server address and port.
Example requests for runtime data:
http://127.0.0.1:8080/serviceruntimedata/cluster
http://127.0.0.1:8080/serviceruntimedata/system
Example requests for file server (both real and virtual files):
http://127.0.0.1:8080/albumart/Blanko.png
http://127.0.0.1:8080/myVirtualPath/receipt.json
Example requests for databases and events:
http://127.0.0.1:8080/RestServices/content/songs:id,name,artist
http://127.0.0.1:8080/RestServices/service/information
http://127.0.0.1:8080/RestServices?5766848&1
GET response format¶
On successful request, the server sends a JSON object. For example:
{
"attributes": {
"1": {
"type": 4,
"value": [
{
"stringvalue": "ContentResultEvent"
}
]
"20": {
8< ...
},
"5": {
"type": 1,
"value": [
{
"intvalue": 65679
}
]
},
"7": {
"type": 4,
"value": [
{
"stringvalue": "Content"
}
]
},
"6": {
"type": 1,
"value": [
{
"intvalue": 1
}
]
},
"8": {
"type": 3,
"value": [
{
"boolvalue": true
}
]
}
}
}
Response package is JSON presentation of protocol buffer defined in <KanziConnectInstallation>/SDK/sources/messages/connect_variant.proto. The identifiers for attributes and attribute types are defined in MessagePackage class. Custom data types and container classes are implemented by recursion and include the definitions of messages as child values inside attribute arrays until there is only primitive value types left. Note that this is going to change in the upcoming versions of Kanzi Connect.
This table lists the most important attributes.
Attribute |
Description |
|---|---|
|
Describes the method or event name. For example, |
|
Method and event attributes use sequential incremental values starting from 20. |
|
Describe the target service for the message. When creating a new session to subscribe to events, Kanzi Connect Server responds with these attributes and expects Kanzi Connect Client to use them on subsequent requests. These attributes are required. |
The GET API completes an HTTP request when new data is available. The first content request always gets completed without delay and subsequent calls are blocked on the server until changed data is available.
To queue requests for new data, you need to set the client identifier. If the given client identifier does not match the identifier stored on the server, the API returns an error. The GET API ignores possible payload on the requests.
POST¶
In the POST API you can send JSON messages similar to Kanzi Connect binary messages to the server and its services. PATCH and PUT requests are handled in a similar manner. Package definitions follow interface definitions stored in <KanziConnectInstallation>/SDK/interfaces/definitions/*.xml files, with a one-to-one mapping.
To post messages to a Kanzi Connect Server, a Kanzi Connect Client application needs valid connection attributes that are enclosed in all messages to and from the server.
Create a new connection by using POST with an empty request to the service URI. Keep in mind that the service definition is case sensitive.
For example:
$http.post('/RestServices/Media', null)On success the server responds with a connection parameters object. Store it on the client and use it in further requests.
At this point no resources in the Kanzi Connect framework are allocated. This is just a token you can use to communicate with the Kanzi Connect service infrastructure.
For example:
{"attributes": { "5": {"type": 1,"value": [{"intvalue": 65679}]}, "7": {"type": 4,"value": [{"stringvalue": "Media"}]}, "6": {"type": 1,"value": [{"intvalue": 1}]} } }
After receiving a token, the client can start generating and posting messages. Usually this means first starting up a new session.
var payload = { "attributes": response.attributes }; payload.attributes["1"] = { "type": 4, "value": [{"stringvalue": "SessionStartMessage"}] } $http.post(uri, payload).then( function () { ... }Communication towards the Kanzi Connect Server takes place using JSON object representation similar to MessagePackage protocol buffer implementation you can find in the SDK sources. Message package consists of arrays of attributes. See GET.
DELETE¶
Use DELETE with the URI that has the client ID set to release the client and all sessions attached to the client.
$http.delete(URI)
For PUSH or GET operations that happen rarely and always in a client-driven manner, it is good practice to create a new object, post the required command and once the sequence is ran, use DELETE to release the client.
Mapping between interface specifications and message¶
For example, media_interface.xml with content
<method name="play_track" return="bool" description="Starts playing given track in given playlist">
<argument name="playlist_id" datatype="int"/>
<argument name="track_id" datatype="int"/>
</method>
maps to playlist_id:1001, track_id:1023
var payload = {
"attributes": connection.attributes
};
payload.attributes["1"] = {
"type": 4,
"value": [{"stringvalue": "MediaPlayTrackMethod"}]
payload.attributes["20"] = {
"type": 1,
"value": [{"intvalue": 1001}]
payload.attributes["21"] = {
"type": 1,
"value": [{"intvalue": 1023}]
$http.post(uri, payload).then(
function () {
...
}
This table describes the naming conventions.
Type |
Naming convention |
Example |
|---|---|---|
Methods. <method> defined in the service description. See the <service>_messages.hpp file to check how code was generated. |
<ServiceIdentifier>+<MethodNameInCamelCase>+Method |
|
Events. <event> defined in the service description. |
<ServiceIdentifier>+<EventNameInCamelCase>+Event |
|
Setters for the runtime data |
<ServiceIdentifier>+Set+<DataPathInCamelCase> |
When defined as <service name="system" namespace="kanzi" description="System interface">
<runtime-data>
<demo>
<temperature type="int" writable="1" />
|
Method and Event arguments follow the declaration order and have their attributes enumerated starting from ATTRIBUTE_KEY_ARGUMENT_1 (= 20). For example, three arguments for the method allocate attributes 20, 21, and 22.
Note:
POST requests are completed once data the Kanzi Connect Server reads them, so they never carry a response to a request.
Use GET requests for reading data from the Kanzi Connect Server.