diff options
| author | Robert Göhler <github@ghlr.de> | 2025-03-11 22:12:38 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2025-03-11 22:12:38 +0100 |
| commit | a97a6563a4bcfe86718709132f5317befe8bbde1 (patch) | |
| tree | 16c1f6edf6f3966614955d3733aee78f00df19b4 | |
| parent | 6aca664962776744cff7f182434fa2e0389f53bc (diff) | |
| parent | 35092bf5a4e1584c729b3e2830a933cb5c4eaa81 (diff) | |
| download | vyos-documentation-a97a6563a4bcfe86718709132f5317befe8bbde1.tar.gz vyos-documentation-a97a6563a4bcfe86718709132f5317befe8bbde1.zip | |
T4406: Add documentation for newly added HTTPS API endpoint
| -rw-r--r-- | docs/automation/vyos-api.rst | 117 |
1 files changed, 115 insertions, 2 deletions
diff --git a/docs/automation/vyos-api.rst b/docs/automation/vyos-api.rst index 60247fae..a9518a00 100644 --- a/docs/automation/vyos-api.rst +++ b/docs/automation/vyos-api.rst @@ -12,8 +12,9 @@ For configuration and enabling the API see :ref:`http-api` Authentication ************** -All endpoints only listen on HTTP POST requests and the API KEY must set as -``key`` in the formdata. +All endpoints except one listen on HTTP POST requests and the API KEY must set +as ``key`` in the formdata. The only public endpoint listens to HTTP GET request +and takes optional query parameters. Below see one example for curl and one for python. The rest of the documentation is reduced to curl. @@ -39,6 +40,118 @@ The rest of the documentation is reduced to curl. ************* API Endpoints ************* +/info +========= + +This is the only endpoint provided by the API service that does not require +authentication and can be queried by anonymous users. Requesting the ``info`` +endpoint you obtain general information about the system, namely the VyOS +version, the system host name and a welcome banner for anonymous users. + +This endpoint responds **only** to HTTP GET requests. + +.. code-block:: none + + curl --location --request GET 'https://vyos/info' + + response + { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname: "vyos" + "banner": "Welcome to VyOS" + }, + "error": null + } + +This endpoint can take two optional query parameters - ``version`` and +``hostname``. These parameters accept all values that can be converted to +Boolean - e.g. ``yes/no``, ``1/0``, ``true/false`` etc, and they dictate whether +to include the respective values into the response. + +If request is sent without any query parameters, the endpoints treats them as +if they are set to ``true`` by default: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?version=1&hostname=1' + + response { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname": "vyos", + "banner": "Welcome to VyOS" + }, + "error": null + } + +If any of the parameters is set to a value that corresponds to ``false``, the +response object will have an empty string instead of the respective value: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?version=0&hostname=1' + + response { + "success": true, + "data": { + "version": "", + "hostname": "vyos", + "banner": "Welcome to VyOS" + }, + "error": null + } + +Please note, that there is no need to specify both parameters if you want to +hide just one of the fields - a missing query parameter is treated as ``true``: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?hostname=no' + + response { + "success": true, + "data": { + "version": "1.5-rolling", + "hostname": "", + "banner": "Welcome to VyOS" + }, + "error": null + } + +Please note, that while you can disable output for both ``hostname`` and +``version``, the ``banner`` is included into the response in any case. + +**Important:** The endpoint accepts **ONLY** ``hostname`` and ``version`` query +parameters. Including any other besides them, or instead of them, will respond +with HTTP 400 Bad Request: + +.. code-block:: none + + curl --location --request GET \ + 'https://192.168.56.119/info?hostname=1&url=https://evilsite.com' + + response { + "success": false, + "error": "{'type': 'extra_forbidden', 'loc': ('query', 'url'), 'msg': 'Extra inputs are not permitted', 'input': 'https://evilsite.com'}", + "data": null + } + +As well as the values passed to the query string are validated to ensure they +are strictly Boolean and won't accept any other data type: + +.. code-block:: none + + curl --location --request GET 'https://vyos/info?hostname=1; eval"sudo rm -rf /" + + response + { + "success": false, + "error": "{'type': 'bool_parsing', 'loc': ('query', 'hostname'), 'msg': 'Input should be a valid boolean, unable to interpret input', 'input': '1; eval \"sudo rm -rf /\"'}", + "data": null + } /retrieve ========= |