2.7. API

2.7.1. Presentation

The Application Programming Interface (API) is the set of endpoints, also known as resources or the end of a URL.
Each of these endpoints enables an action to be performed on the GBox, or information to be returned, without having to go through the GBox graphical interface.
This makes it easier to share and integrate GBox functions and data into existing architectures.
Each of these endpoints has a simple syntax.
These endpoints are predetermined: the list of endpoints is limited and is displayed by theme (analysers...).

Note

The list of endpoints is provided in the Endpoint list paragraph.

These endpoints can be executed:

  • Via SWAGGER (Use via the swagger graphical interface):
    This enables endpoints to be used, its parameters to be understood, its execution to be tested, and its results to be analysed
  • Via CURL (Use via CURL) :
    This enables a Curl request to be executed directly without going through the graphical interface.

2.7.2. Use via the swagger graphical interface

Each endpoint of the API:

  • Performs a specific operation. Its name and description are indicated in the GUI or in the list Endpoint list

  • Performs one of four possible methods: GET (Obtain), DELETE (Delete), POST (Publish), PUT (Modify)

  • Needs authentication rights that are the same as for the graphical interface (Operators or Administrators)

  • May need operating, input and/or output parameters: for example, in the case of a filter, the value of this filter must be indicated.

All this information is visible in the swagger graphical interface. It is therefore the documentation for all our API endpoints.
The swagger GUI description is given in the Overview of the API GBOX interface.
To implement the swagger interface, see the procedure in the Using an API endpoint.

This interface enables:

  • A list of existing endpoints by theme

  • Details of any parameters for running an endpoint

  • Information on the expected result, data template, and an example with default values

  • Running queries

  • Retrieving the Curl command equivalent to the request via the API

2.7.3. Use via CURL

It is possible to run an endpoint using a CURL command.
This command can be accessed via the swagger graphical interface, after selecting the endpoint, enter any parameters, and then run the endpoint.
The curl command is displayed in the `Responses` area.

Note

Send a request to list the GBox engines (endpoint api/analysers):

curl -X GET "https://x.x.x.x/api/analysers/" -H  "accept: application/json" -H  "authorization: Basic dG90bzpTYW5kcmluZSwxMDA=" -H  "X-CSRFToken: PsMZMavgOibfe5giFCImu0YYTWqvB2AdhR1y"

where x.x.x.x is the IP address of the Gbox.

The swagger GUI description is given in the Overview of the API GBOX interface.
To implement the swagger interface, see the procedure in the Using an API endpoint.

2.7.4. Authentication and access to the GBox API

Access to the swagger graphical interface is via the GBox interface and then pressing the `API` button.
Authentication on the GBox enables access to the GBox API (for more information, see the Title bar).
The use of curl requests requires authentication to be carried out in the request.
This authentication is carried out using name/password pairs or tokens defined in the `Admin-GBox - Accounts` screen of the Web UI.