OpenCPN Partial API docs
Public Member Functions | Public Attributes | List of all members
AbstractRestServer Class Referenceabstract

Opencpn REST API. More...

#include <rest_server.h>

Inheritance diagram for AbstractRestServer:
RestServer

Public Member Functions

virtual bool StartServer (const fs::path &certificate_location)=0
 Start the server thread.
 
virtual void StopServer ()=0
 Stop server thread, blocks until completed.
 
virtual std::string GetEndpoint ()=0
 Return HTTPS url to local rest server.
 

Public Attributes

EventVar activate_route
 Notified with a string GUID when user wants to activate a route.
 
EventVar reverse_route
 Notified with a string GUID when user wants to reverse a route.
 

Detailed Description

Opencpn REST API.

Supported endpoints:

GET /api/ping?api_key=<pincode> &source=<ip address>
Basic ping check, verifies api_key i. e., the pairing.

  • Parameters:
    • source=<ip> Mandatory, origin ip address or hostname.
    • api_key=<key> Mandatory, as obtained when pairing, see below.
  • Returns: {"result": <code>, "version": <version>} <version> is a printable version like 5.9.0

POST /api/rx_object?api_key=<pincode>&source=<ip address>&force=1
Upload GPX route(s), track(s) or waypoint(s).

  • Parameters:
    • source=<ip> Mandatory, origin ip address or hostname.
    • api_key=<key> Mandatory, as obtained when pairing, see below.
    • force=<1> if present, the host object is unconditionally updated. If not, host may run a "OK to overwrite" dialog.
    • activate=<1> Optional, activate route or waypoint after transfer
  • Body: xml-encoded GPX data for one or more route(s), track(s) and/or waypoint(s)
  • Returns: {"result": <code>}

GET /api/writable?guid=<guid>
Check if route or waypoint with given guid is writable.

  • Parameters:
    • source=<ip> Mandatory, origin ip address or hostname.
    • api_key=<key> Mandatory, as obtained when pairing, see below.
    • guid=<guid> Route, waypoint or track guid.
  • Returns: {"result": <code>}

GET /api/get-version
Return current server version string. Does not require api_key or source.

  • Parameters: None
  • Returns (example): {"version": "5.8.9" }

GET /api/list-routes
Return list of available routes

  • source=<ip> Mandatory, origin ip address or hostname.
  • api_key=<key> Mandatory, as obtained when pairing, see below.
  • Returns json data { "version": "5.8.0", "routes": [ ["guid-1": "name1" ], ["guid-2": "name2" ], ... ] }

GET /api/activate-route
Activate an existing route.

  • source=<ip> Mandatory, origin ip address or hostname.
  • api_key=<key> Mandatory, as obtained when pairing, see below.
  • guid=<guid> Route guid.
  • Returns json data (activating already active route silently ignored) {"result": <code>}

GET /api/reverse-route
Reverse an existing route

  • source=<ip> Mandatory, origin ip address or hostname.
  • api_key=<key> Mandatory, as obtained when pairing, see below.
  • guid=<guid> Route guid.
  • Returns json data {"result": <code>}

POST /api/plugin-msg Upload string message forwarded to all plugins

  • Parameters:
    • source=<ip> Mandatory, origin ip address or hostname.
    • api_key=<key> Mandatory, as obtained when pairing, see below.
    • id=<id> Mandatory, message id used by listeners.
  • Body:
    • Arbitrary text.
  • Returns: {"result": <code>}

Authentication uses a pairing mechanism. When an unpaired device tries to connect, the API generates a random pincode which is sent to the connecting party where it is displayed to user. User must then input the pincode in the server-side GUI thus making sure she has physical access to the server.

Result codes are as defined in RestServerResult.

Definition at line 221 of file rest_server.h.

The documentation for this class was generated from the following file: