5.4.1. Overview of the API GBOX interface

The API interface enables:
  • Displaying a list of existing endpoints by theme

  • Filtering of this list

  • Finding out all the information about each endpoint

  • running the endpoint

  • Finding out its curl command

  • Finding out its URL request

Note

The GBox API graphical interface is called swagger.

After pressing the `API` button on the title bar, the following screen is displayed.
The window includes:
../../_images/GBOX-API-01.PNG

Item

Description

1

`Schemes`: setting indicating the protocol used (HTTPS)

2

Current account name: here administrator account

3

`Django Logout` button: enables exiting the API graphical interface

4

`Authorize` button: enables setting the authentication required in curl commands

5

Endpoints are sorted by theme (tag)

6

Filter field: enables the filtering of themes


5.4.1.1. Detail for an endpoint

The information displayed for an endpoint is as follows:

../../_images/GBOX-API-02.PNG

Item

Description

1

Title line. It includes the action (here GET), the name of the endpoint (here /template), the accesses (here Administrators and Operators), the description of the endpoint

2

`Try it out` button: executes the endpoint with the current parameters

10

`Parameters` field: displays the optional or mandatory settings for executing the query. To find out which parameters are mandatory, refer to zone (6).
This zone includes:

9

  • `is_default` parameter: enables the default template to be selected. The `true` setting must be entered.

8

  • The `name` parameter: defines the name of the template from which information is to be retrieved.
    Look in the `Model` window for the type (here string) and whether the parameter is mandatory (here * = mandatory).

7

  • `ordering` field: enter the name of the field used to order the response.

6

`Responses` zone: this zone displays information depending on whether or not the `Try it out` button has been enabled.

Note

If a parameter is mandatory, an asterisk with `required` is displayed.

Note

Parameters cannot be entered on this screen. To do this, the query must be executed.


5.4.1.1.1. `Responses` field if the `Try it out` button is not enabled.

If the `Try it out` button is not enabled, then the `Responses` zone contains information about the expected response:

../../_images/GBOX-API-02.PNG

Item

Description

5

`Template` link: by clicking on this text, the window (3) displays the template for the expected response.

4

`Example Value` link: by clicking on this text, the window (3) displays an example of the expected response with example values.
The values are for the integer type (value 0), for the string type (value = string), for the boolean type (value = true).

3

View field: contains the content selected by the active option (4) or (5).
An example of the content is shown below.

5.4.1.1.1.1. Example of an output template

The output template provides the structure of the data that will be displayed as output, i.e. after the query is executed.

../../_images/GBOX-API-04.PNG

Item

Description

1

`id`: template number. For this parameter, its characteristics are indicated (type, title, etc.).

2

`name`: template name. For this parameter, its characteristics are indicated (type, title, length. etc.).

3

`is_default`: field defines whether the current template is the default template. The response is a Boolean (true/false value).

4

`options`: field defining possible options.

5

`analysers`: field defining the information for all the engines.

6

`Analyser`: field defining information for a single engine.


5.4.1.1.2. Example with default values

In this example, the information is displayed with the following default values:

  • integer parameters are displayed with the number `0`.

  • string parameters are displayed with the text `string`.

  • boolean parameters are displayed with the text `true`.

../../_images/GBOX-API-05.PNG

The marking is the same as in the output template.


5.4.1.1.3. `Responses` field if the `Try it out` button is enabled.

Once the `Try it out` button is clicked, the parameter input area is activated.
The following screen is displayed:
../../_images/GBOX-API-06.PNG

Item

Description

1

`Execute` button: enables the request to be executed with the current parameters

2

`Cancel` button: aborts the query

3

The `Responses` zone has not changed

After clicking on the `Execute` button, the query is started and the following window is displayed.

../../_images/GBOX-API-07.PNG

Item

Description

1

`Clear` button: enables returning to the status before execution

2

`Curl` display area: displays the Curl request

3

`URL` display area: displays the URL request

4

`Code`: If code 200 then execution ok. If the message `code 400 Undocumented Error Bad Request` is displayed, check whether the mandatory parameters have been entered correctly.

6

`id 1`: template number 1

7

`Name gmalcore` : engine id 2 Gmalcore

8

id 3: template number 3

9

`Responses headers`: area describing the response header

10

`Request duration`: value in ms of the request duration