How to use Pixotope Gateway

Introduction

Pixotope Gateway is a service to relay HTTP requests to Data Hub and to respond with meaningful data when it makes sense. The service is automatically launched by Pixotope Daemon. There’s an instance of it running on every Pixotope machine.

Network

• Listening/Sending

  • Port 16208

Data hub PX_Datahub.exe as well as Pixotope Gateway PX_Gateway.exe, which are auto started by Pixotope, are expected to run on your machine.

Sending HTTP Requests

HTTP POST messages with a JSON data body are the main way of publishing messages via Pixotope Gateway. The whole functionality of a regular ZeroMQ Data Hub client should be available to anyone using HTTP POST.

Request specification

Target URL

The target URL is a versioned Pixotope Gateway endpoint following this pattern:

http://[IPAddress]:[Port]/[Gateway]/[Version]/publish

• IPAddress - local network IP of the machine running Pixotope Gateway,

• Port - port Pixotope Gateway listens on, 16208 by default (can be configured),

• Version - Pixotope version used, for example: 2.2.0

Requests based on an older version (using an older version number) should still work unless there has been a breaking API change.

For example, for Pixotope 2.2.0 and a localhost URL, HTTP publishing would be:

http://localhost:16208/gateway/2.2.0/publish

Request body

Data body is a JSON containing Topic and Message objects, formatted in accordance with the general Data Hub guidelines.

Attachment objects are not supported by Pixotope Gateway

Learn more about Pixotope API - Message Scheme

Pixotope Gateway specifics

• Any field signifying the identity of the sender (Source, RespondTo) don’t need to be sent. These fields will be filled in by Pixotope Gateway.

• For Call messages, the ID field will always be set/overridden by Pixotope Gateway. It therefore doesn’t have to be included.

Request header

HTTP headers can be empty.

Example

Python example to Set CompositingColorSpace value on the Store:

import json, requests
url = "http://localhost:16208/gateway/2.2.0/publish"
payload = json.dumps({
                    "Topic": {
                        "Type": "Set",
                        "Target": "Store",
                        "Name": "State.General.CompositingColorSpace"
                    },
                    "Message": {
                        "Value": "Video"
                    }
})
response = requests.request("POST", url, data=payload)

Sending URL-only HTTP requests

Some messages can be formatted using a URL only HTTP GET method. This will make them easier to execute, but certain complexities will not be available (for example setting the whole struct with Set at once).

Use the Target URL (shown above) and add named URL parameters corresponding to Topic and Message fields of a regular Data Hub request.

http://localhost:16208/gateway/2.2.0/publish?Type=Set&Target=Store&Name=State.General.CompositingColorSpace&Value=Video

Example

Python example to Set camera Delay value on the Store:

import requests
requests.request("GET", "http://localhost:16208/gateway/2.2.0/publish?Type=Set&Target=Store&Name=State.General.CompositingColorSpace&&Value=Video")

You can also just execute the above URL from your web browser. Try it!
It can be useful for experimenting with your project.

Call type requests

Additionally, for Call Type requests, you can add named RPC arguments by adding URL parameters with a “Param“ prefix.

Example

Python example to Call a method CallFunction on TJCGWS040-Engine:

import requests
requests.request("GET", "http://localhost:16208/gateway/2.2.0/publish?Target=TJCGWS040-Engine&Type=Call&Method=CallFunction&ParamObjectSearch=level_blueprint&ParamFunctionName=Test")

Going against the standard practice we allow changing the state of our system with HTTP GET requests. This will be configurable in the future.

HTTP response

Any HTTP request sent to Pixotope Gateway will result in a response. In many cases the response is going to be quite minimal (for calls that only trigger changes without querying any data).

Responses to the different Type of the request

Custom timeout

If it so happens that a service targetted by your call doesn’t respond Gateway will timeout after 1000 ms by default.

This value can be changed if you expect the targetted service to need more leeway.

URL-only example:

http://localhost:16208/gateway/2.2.0/publish?Type=Set&...&Timeout=2000")

Python example:

import json, requests
url = "http://localhost:16208/gateway/2.2.0/publish"
payload = json.dumps({
                    "Topic": {...},
                    "Message": {...},
                    "Timeout": 2000
})
response = requests.request("POST", url, data=payload)