PRJ16 WebAPI

PRJ16 4.5 and newer feature a new WebAPI plugin. This plugin offers a RESTful API for accessing PRJ16 Server instances via HTTP. There are two possible usage scenarios:

  • Local: WebAPI server on each computer running along with the PRJ16 Server and thus connects to localhost

  • Proxy: WebAPI server on a server node, acting as a proxy by connecting to the requested hosts

While running the WebAPI server locally can be beneficial in terms of performance, it requires the deployment of individual SSL certificates on all computers.

The WebAPI plugins also offers a CLI module, so the WebAPI server can be run standalone easily via PRJ16-cli webapi runserver.

The following sections describe all supported API calls.

General

  • When a call succeeds, the indicated responses can be expected with HTTP status code 200.

  • Any errors will be indicated through a corresponding (non-unambiguous) HTTP status codes and an additional error object in the response body, e.g. {"error":{"code":6,"message":"Authentication failed"}}

Error

Error code

HTTP status code

NoError

0

200 (OK)

InvalidData

1

400 (BadRequest)

InvalidConnection

2

401 (Unauthorized)

InvalidFeature

3

400 (BadRequest)

InvalidCredentials

4

400 (BadRequest)

AuthenticationMethodNotAvailable

5

400 (BadRequest)

AuthenticationFailed

6

401 (Unauthorized)

ConnectionLimitReached

7

429 (TooManyRequests)

ConnectionTimedOut

8

408 (RequestTimeout)

UnsupportedImageFormat

9

503 (ServiceUnavailable)

FramebufferNotAvailable

10

503 (ServiceUnavailable)

FramebufferEncodingError

11

500 (InternalServerError)

ProtocolMismatch

12

501 (NotImplemented)

Connection management & authentication

General

  • Idle (inactive) connections are closed automatically after 60 s per default (configurable through the WebAPI/ConnectionIdleTimeout setting)

  • Unauthenticated connections are closed automatically after 15 s per default (configurable through the WebAPI/ConnectionAuthenticationTimeout setting)

  • Authenticated connections have a limited lifetime and are closed automatically after 3 hours per default (configurable through the WebAPI/ConnectionLifetime setting)

Get authentication methods supported by host

  • URL: /api/v1/authentication/<HOST>

  • Method: GET

  • Response: { "methods": [ "<UUID1>", "<UUID2", ... ] }

Create new connection and perform authentication

  • URL: /api/v1/authentication/<HOST>

  • Method: POST

  • Data: { "method": "<AUTH-METHOD-UUID>", "credentials": <METHOD-SPECIFIC-CREDENTIALS> }

  • Response: { "connection-uid": "<CONNECTION-UID>", "validUntil": <UTC-TIMESTAMP> }

  • The returned connection UUID identifies a single connection to a host and needs to be passed in the Connection-Uid header field in all subsequent API calls

  • The connection’s lifetime ends at the time specified in the validUntil field

  • <HOST> should be localhost when connecting to WebAPI servers running on target computers

Close connection

  • URL: /api/v1/authentication/<HOST>

  • Method: DELETE

  • Headers: { Connection-Uid: <CONNECTION-UID> }

  • Response: { }

Authentication methods

Name

UUID

Credentials

AuthKeys

0c69b301-81b4-42d6-8fae-128cdd113314

{ "keyname": "<NAME>" (e.g. "teacher"), "keydata": "<PEM-ENCODED-PRIVATE-KEY>" }

AuthLDAP (PRJ16 >= 5)

6f0a491e-c1c6-4338-8244-f823b0bf8670

{ "username": "<LDAP-USERNAME>", "password": "<LDAP-PASSWORD>" }

AuthLogon

63611f7c-b457-42c7-832e-67d0f9281085

{ "username": "<USERNAME>", "password": "<PASSWORD>" }

AuthSimple (PRJ16 >= 5)

73430b14-ef69-4c75-a145-ba635d1cc676

{ "password": "<MASTER-PASSWORD>" }

Framebuffer

Get current framebuffer image

  • URL: /api/v1/framebuffer?format=[png|jpeg]&compression=[1-9]&quality=[1-100]&width=NNNN&height=NNNN

  • Method: GET

  • format

    • Optional

    • Defaults to png

  • compression

    • Optional

    • Used for the PNG format only

    • default=5

    • 1=no compression, 9=highest compression

  • quality

    • Optional

    • Used for the JPEG format only

    • default=75

    • 1=lowest quality, 100=highest quality

  • width/height

    • Optional

    • If none of both is not specified, the original framebuffer image will be returned

    • If either one is specified, the corresponding counterpart will be calculated automatically while keeping the aspect ratio

  • Response: <IMAGE-DATA>

Feature control

Get available features

  • URL: /api/v1/feature

  • Method: GET

  • Headers: { Connection-Uid: <CONNECTION-UID> }

  • Response: [ <FEATURE OBJECTS> ]

Start or stop feature

  • URL: /api/v1/feature/<FEATURE-UID>

  • Method: PUT

  • Data: { "active": [true/false], "arguments": <ARGUMENTS> }

  • Arguments are feature specific and described in the feature table below

  • Headers: { Connection-Uid: <CONNECTION-UID> }

  • Response: { }

Query feature status

  • URL: /api/v1/feature/<FEATURE-UID>

  • Method: GET

  • Headers: { Connection-Uid: <CONNECTION-UID> }

  • Response: { "active": [true/false] }

  • Only applies to features implementing a certain mode such as ScreenLock. All features implementing simple actions will never be reported as active.

Available features

Name

UUID

Arguments

ScreenLock

ccb535a2-1d24-4cc1-a709-8b47d2b2ac79

<none>

InputDevicesLock (PRJ16 >= 4.5.0)

e4a77879-e544-4fec-bc18-e534f33b934c

<none>

UserLogin

7310707d-3918-460d-a949-65bd152cb958

{ "username": <USERNAME>, "password": <PASSWORD> }

UserLogoff

7311d43d-ab53-439e-a03a-8cb25f7ed526

<none>

Reboot

4f7d98f0-395a-4fff-b968-e49b8d0f748c

<none>

PowerDown

6f5a27a0-0e2f-496e-afcc-7aae62eede10

<none>

DemoServer

e4b6e743-1f5b-491d-9364-e091086200f4

{ "demoAccessToken": <TOKEN> }

FullScreenDemoClient

7b6231bd-eb89-45d3-af32-f70663b2f878

{ "demoAccessToken": <TOKEN>, "demoServerHost": <DEMO-SERVER-HOST-ADDRESS> }

WindowDemoClient

ae45c3db-dc2e-4204-ae8b-374cdab8c62c

{ "demoAccessToken": <TOKEN>, "demoServerHost": <DEMO-SERVER-HOST-ADDRESS> }

StartApp

da9ca56a-b2ad-4fff-8f8a-929b2927b442

{ "applications": ["<APP1-PATH-WITH-ARGUMENTS>", "<APP2-PATH-WITH-ARGUMENTS>", ...] }

OpenWebsite

8a11a75d-b3db-48b6-b9cb-f8422ddd5b0c

{ "websiteUrls": ["<URL1>", "<URL2>", ...] }

TextMessage

e75ae9c8-ac17-4d00-8f0d-019348346208

{ "text": "..." }

  • A demo token is an arbitrary ASCII string (e.g. base64-encoded random data) with a recommended length of at least 16 bytes

User information

  • URL: /api/v1/user

  • Method: GET

  • Response: { "login": "<USER-LOGIN-NAME>", "fullName", "<FULL-NAME-OF-USER>" }

  • If no user is logged on, the login and fullName fields are empty

Session information

  • URL: /api/v1/session

  • Method: GET

  • Response: { "sessionId": <SESSION-ID>, "sessionUptime", <SESSION-UPTIME-IN-SECONDS>, "sessionClientAddress": "<ADDRESS-OF-SESSION-CLIENT>", "sessionClientName": "<SESSION-CLIENT-NAME>", "sessionHostName": "<NAME-OF-SESSION-HOST>" }

    • sessionId - an integer representing the session ID assigned by the PRJ16 Service - to be used as offset to the server ports to access the corresponding session server

    • sessionUptime - the number of seconds that elapsed since the session has been opened (e.g. user logon time)

    • sessionClientAddress - the host/IP address of the client which is connected to the session (e.g. the host running an RDP client)

    • sessionClientName - the name the client which is connected to the session (e.g. the host running an RDP client)

    • sessionHostName - the name of the host on which the session is running, usually the local hostname