Access the Web API

The Web API is divided into two main parts:

• The HTTPS REST API is used for stateless requests like authentication or resources.

• The streaming APIs are used for continuous data like video streaming, PLC data, or alarms.

HTTPS REST API

The G-Core Web API is installed as a service and hosts a Swagger user interface in which developers can find the description of the complete interface: https://<server-ip>:13333/swagger/index.html (for example: https://127.0.0.1:13333/swagger/index.html).

It can be accessed with any modern browser (Chrome, Safari, Firefox, and Edge). You can build an HTTP web client against these GET and POST commands in any language, or build a C# application and use the wrapped HTTP functions in a class.

Streaming APIs

The streaming APIs uses two different technologies:

• Video streaming uses the WebSocket protocol directly, based on a TCP connection.

• PLC data and alarms use SignalR. SignalR negotiates its own transport (WebSockets, Server-Sent Events, or long polling), so a SignalR client library is required — a plain WebSocket connection will not work. Only the JSON protocol is supported.

The respective documentation can be accessed via the following URLs:

• Video streaming: https://<server-ip>:13333/asyncapi/media/ui/index.html

• PLC: https://<server-ip>:13333/asyncapi/plc/ui/index.html

• Alarms: https://<server-ip>:13333/asyncapi/alarms/ui/index.html

On these pages you will find the necessary documentation for using the streaming endpoints.

Authentication

All streaming endpoints require the access token obtained from the REST API login endpoint. Since browsers cannot set custom headers during a WebSocket handshake, the token can be supplied in several ways:

• Video streaming: Authorization: Bearer <token> header, an Authorization cookie, or the Sec-WebSocket-Protocol header.

• SignalR hubs: the access_token query parameter (the SignalR standard) or the Authorization: Bearer <token> header.

Authentication in Swagger

You can perform the authentication directly in the Swagger user interface. The result is a tuple, which you should subsequently use in any other requests to be authenticated. The tuple consists of an AccessToken and a RefreshToken.

Token	Validity	Use
AccessToken	Valid for a period of 15 minutes.	For HTTP requests, the token can be used in the Authorization header. For example: Authorization: Bearer <AccessToken>
RefreshToken	Valid for 7 days. Each RefreshToken is only valid once.	The token can be used to acquire new access tokens via the /api/1/ RefreshLogin endpoint, which also returns a tuple of AccessToken and RefreshToken.

The authentication endpoint /api/1/Login is rate limited to a certain number of requests in the default settings. Per client IP there are 100 requests per 10 Minutes allowed. This setting can be configured in the appsettings.json file in the IpRateLimiting section.

In Swagger, enter the token to perform the authentication:

1. In Swagger, click Authorize in the top right corner.

2. Enter the word Bearer followed by a space and the token you received from the login endpoint (Bearer <AccessToken>).

3. Then you can try any other endpoint in Swagger.

→ This authentication is also required for the WebSocket API.

Authentication of the WebSocket API

There are two supported ways to authenticate the WebSocket API:

• You can set the token in an authorization cookie.

  Copy

  ClientWebSocket _webSocket = new ClientWebSocket();
  var token = "...";
  _webSocket.Options.Cookies = new System.Net.CookieContainer();
  _webSocket.Options.Cookies.Add(new Uri(String.Format("ws://{0}/", host)), new System.Net.Cookie("Authorization", token));
  _webSocket.ConnectAsync(
          new Uri(String.Format("ws://{0}/api/1/stream/video?MediaChannelIdentifier={1}", host, mediaChannel)), cancellationToken).Wait();

• You can set the token as in the protocol header.

  Copy

  this.socket = new WebSocket(url, accessToken);