Access the Web API

The Web API is divided into two main parts:

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

  • The WebSocket API is used for connected requests like video streaming or PLC data.

HTTPS REST API

The HTTPS REST API is documented with Swagger. You can access the documentation via https://<server-ip>:13333/swagger/index.html (for example: https://127.0.0.1:13333/swagger/index.html) in any modern browser (Chrome, Safari, Firefox, and Edge).

The G-Core Web API is installed as a service and contains a swagger API where developer can get the description of the complete interface (https://localhost:13333/swagger/index.html).

You can build an HTTP webclient and access these GET and POST commands or you can build a c# application and use the wrapped HTTP function in a class.

WebSocket API

The WebSocket API is using the WebSocket protocol based on a TCP connection.

The respective WebSocket API documentation can be accessed via the following URLs:

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

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

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

Authentication

Use the authentication endpoint /api/1/Login to authenticate with the G-Core Web API. The G-Core username and password are used for authentication.

Authentication in Swagger

You can perform the authentication directly in the Swagger UI. 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

Valitity

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);