.. _HTTP:

HTTP Interface
==============

The HTTP REST API provides access to almost any functionality of the `PlatformPilot` via the HTTP protocol.

The HTTP server is enabled by default on port ``8888``, however it can be disabled by setting ``enable_http_server`` to ``false``.

The REST API is available on the path ``http://localhost:8888/api/``. (replace `localhost` with your target machine)

See also :ref:`HttpProxy`.


Login
-----

Some functionality requires special permissions, see :ref:`users`.

To gain necessary permissions you need to login to the HTTP server as follows::
	
	curl -I "http://localhost:8888/server/login?user=neo-user&passwd_plain=neobotix"
	HTTP/1.1 200 OK
	...
	Set-Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8; Path=/; Max-Age=86400; SameSite=Strict;

The response will contain a session cookie which can be used as follows::

	curl -H "Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8" http://localhost:8888/api/request/...


Services
--------

All modules of the `PlatformPilot` are available via the path ``/api/request/``.

To get an overview of the available modules::

	curl http://localhost:8888/api/request/
	["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "HybridPlanner/", ...]

The available methods of a module can be queried as follows::

	curl http://localhost:8888/api/request/HybridPlanner/
	["append_goal", "append_goal_position", "append_goal_positions", "append_goal_station", ...]

A method can be called as follows::

	curl -X POST http://localhost:8888/api/request/PilotServer/get_state
	{"__type": "pilot.PilotState", ...}
	
	curl -H "Cookie: ..." -X POST -d '{"name": "Station1"}' \
		http://localhost:8888/api/request/HybridPlanner/set_goal_station

The parameters of a function are supplied as a JSON object via POST data.

You may need to be logged in to access certain functions, see above.


Topics
------

Almost all topics of the `PlatformPilot` are available via the path ``/api/topic/``.

To get an overview of the available topics::

	curl http://localhost:8888/api/topic/
	["input/", "local_planner/", "navigation/", "platform/", "sensors/", "task_handler/", "tf/", "tfd/", "vnx/"]
	
	curl http://localhost:8888/api/topic/platform/
	["info", "odometry", "pilot_state", "system_state"]
	
To get the latest sample data of a topic::

	curl http://localhost:8888/api/topic/platform/odometry
	{"__type": "pilot.Odometry", "time": 1613656049067588, ...}

To get a tree of the lastest sample data of a domain::

	curl http://localhost:8888/api/topic/platform
	{"info": {"__type": "pilot.PlatformInfo", ...}, ...}

To publish a data sample on a topic::

	curl -H "Cookie: ..." -X POST -d '{"topic": "test.topic", "sample": {"__type": "pilot.Pose2D", ...}}' \
		http://localhost:8888/api/request/HttpProxy/publish

Note that a ``__type`` field needs to be specified containing the type name of the sample, such as ``pilot.Pose2D`` for example.


Configuration
-------------

The current configuration tree can be viewed via the path ``/api/config/``.

To access protected configuration values, a special permission `PROTECTED_CONFIG` is required, see :ref:`vnx.permission_e`.

To get an overview of the available config options::

	curl http://localhost:8888/api/config/
	["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "GridMapping/", ...]

	curl http://localhost:8888/api/config/GridLocalization/
	["broadcast_tf", "confidence_gain", "constrain_threshold", "constrain_threshold_yaw", "gain_factor", ...]
	
To query a specific config value::

	curl http://localhost:8888/api/config/GridLocalization/gain_factor
	0.01
	
To query a sub-tree of the configuration::

	curl http://localhost:8888/api/config/GridLocalization
	{"broadcast_tf": true, "confidence_gain": 0.01, "constrain_threshold": 0.1, "constrain_threshold_yaw": 0.2, "gain_factor": 0.01, ...}

To query the entire configuration tree::

	curl http://localhost:8888/api/config
	{...}


Log
---

The terminal output log messages are available via the path ``/api/log/``.

Each message is of type :ref:`vnx.LogMsg`.

To get all errors which occured since startup::

	curl http://localhost:8888/api/log/errors
	[...]

To get all recent messages::

	curl http://localhost:8888/api/log/recent
	{"1": [...], "2": [...], "3": [...], "4": [...]}
	
To get recent warnings only::

	curl http://localhost:8888/api/log/recent/2
	[...]
	
The log levels are as follows:

* 1 = ERROR
* 2 = WARN
* 3 = INFO
* 4 = DEBUG

Log messages are also written to disk and can be accessed via ``http://example:8888/user/data/logs/``.


Events
------

A history of events is available via the path ``/api/events/``.

Each entry is of type :ref:`pilot.Event` or any of it's derived types such as :ref:`pilot.Incident`.

To get a list of recent events::

	curl http://localhost:8888/api/events/recent
	[...]
	
To get recent error events only::

	curl http://localhost:8888/api/events/errors
	[...]

The latest events are at the end of the respective list.


Views
-----

For certain data types there are special views available via the path ``/api/view/``.

To get a cost map (see :ref:`pilot.CostMapData`) as a PGN image::

	curl "http://localhost:8888/api/view/cost_map?topic=navigation.local_cost_map&color=true&alpha=128" > local_cost_map.png

To get a grid map (see :ref:`pilot.OccupancyMapData`) as a PGN image::

	curl "http://localhost:8888/api/view/occupancy_map?topic=navigation.grid_map&alpha=255" > grid_map.png