Skip to content

REST

rest

X-Plane Web API access through REST API

Classes:

  • REST_KW –

    REST requests and response JSON keywords.

  • XPRestAPI –

    XPlane REST API

REST_KW 


              flowchart TD
              xpwebapi.rest.REST_KW[REST_KW]

              

              click xpwebapi.rest.REST_KW href "" "xpwebapi.rest.REST_KW"

REST requests and response JSON keywords.

XPRestAPI 

XPRestAPI(
    host: str = "127.0.0.1",
    port: int = 8086,
    api: str = "/api",
    api_version: str = "v1",
    use_cache: bool = False,
    retry_attempts: int = 1,
    retry_backoff: float = 0.0,
    retry_backoff_max: float = 5.0,
    pool_connections: bool = False,
    max_connections: int | None = None,
    max_keepalive_connections: int | None = None,
    keepalive_expiry: float | None = None,
    timeout: float | None = None,
    read_only: bool = False,
)


              flowchart TD
              xpwebapi.rest.XPRestAPI[XPRestAPI]
              xpwebapi.api.API[API]

                              xpwebapi.api.API --> xpwebapi.rest.XPRestAPI
                


              click xpwebapi.rest.XPRestAPI href "" "xpwebapi.rest.XPRestAPI"
              click xpwebapi.api.API href "" "xpwebapi.api.API"

XPlane REST API

Adds cache for datarefs and commands meta data.

There is no permanent connection to REST API. When needed, connection can be probed with XPRestAPI.connected which is True if API is reachable. Most API call test for reachability before issuing their request(s).

See Also

X-Plane Web API — REST API

Methods:

Attributes:

capabilities property 

capabilities: dict

Fetches API capabilties and caches it

connected property 

connected: bool

Whether API is reachable

API may not be reachable if
  • X-Plane version before 12.1.4,
  • X-Plane is not running

rest_api_reachable property 

rest_api_reachable: bool

Whether API is reachable

API may not be reachable if
  • X-Plane version before 12.1.4,
  • X-Plane is not running

rest_url property 

rest_url: str

URL for the REST API

status property writable 

status: CONNECTION_STATUS

Connection status

status_str property 

status_str: str

Connection status as a string

uptime property 

uptime: float

Time X-Plane has been running in seconds since start

Value is fetched from simulator dataref sim/time/total_running_time_sec

use_cache property writable 

use_cache: bool

Use cache for object meta data

use_rest property writable 

use_rest: bool

Should use REST API for some purpose

xp_version property 

xp_version: str | None

Returns reported X-Plane version from simulator

beacon_callback 

beacon_callback(connected: bool, beacon_data: 'BeaconData', same_host: bool)

Minimal beacon callback function.

Provided for convenience.

Parameters:

  • connected

    (bool) –

    Whether beacon is received

  • beacon_data

    (BeaconData) –

    Beacon data

  • same_host

    (bool) –

    Whether beacon is issued from same host as host running the monitor

changed 

changed(dataref, value) -> bool

If rounding applies, determine if value has changed according to its rounding.

close 

close() -> None

Close the underlying HTTP session.

command 

command(path: str) -> Command

Create Command with current API

Parameters:

  • path

    (str) –

    Command "path"

Returns:

  • Command ( Command ) –

    Created command

commands_meta 

commands_meta(
    commands: list[Command],
    fields: list[str] | str = "all",
    start: int | None = None,
    limit: int | None = None,
) -> list[CommandMeta]

Get dataref meta data through REST API for all dataref supplied

@todo: commands_meta(self, dataref, fields:list[str]|str = "all", start: int|None = None, limit: int|None = None) # fields={id, name, description, all}

dataref 

dataref(path: str, auto_save: bool = False) -> Dataref

Create Dataref with current API

Parameters:

  • path

    (str) –

    Dataref "path"

  • auto_save

    (bool, default: False ) –

    Save dataref back to X-Plane if value has changed and writable (default: False)

Returns:

  • Dataref ( Dataref ) –

    Created dataref

dataref_meta 

dataref_meta(dataref, fields: list[str] | str = 'all') -> DatarefMeta | None

Get dataref meta data through REST API

@todo: dataref_meta(self, dataref, fields:list[str]|str = "all") # fields={id, name, value_type, all}

dataref_value 

dataref_value(
    dataref: Dataref, raw: bool = False, no_decode: bool = False
) -> DatarefReadResult

Get dataref value through REST API

Value is not stored or cached.

datarefs_meta 

datarefs_meta(
    datarefs: list[Dataref],
    fields: list[str] | str = "all",
    start: int | None = None,
    limit: int | None = None,
) -> list[DatarefMeta]

Get dataref meta data through REST API for all dataref supplied

@todo: datarefs_meta(self, dataref, fields:list[str]|str = "all", start: int|None = None, limit: int|None = None) # fields={id, name, value_type, all}

execute_command 

execute_command(command: Command, duration: float = 0.0) -> APIResult

Executes Command through REST API

Returns:

bool: success of operation

get_command_meta_by_id 

get_command_meta_by_id(ident: int) -> CommandMeta | None

Get command meta data by command identifier

get_command_meta_by_name 

get_command_meta_by_name(path: str) -> CommandMeta | None

Get command meta data by command path

get_dataref_meta_by_id 

get_dataref_meta_by_id(ident: int) -> DatarefMeta | None

Get dataref meta data by dataref identifier

get_dataref_meta_by_name 

get_dataref_meta_by_name(path: str) -> DatarefMeta | None

Get dataref meta data by dataref name

get_rest_meta 

get_rest_meta(
    obj: Dataref | Command, force: bool = False
) -> DatarefMeta | CommandMeta | None

Get meta data from X-Plane through REST API for object.

Fetches meta data and cache it unless force = True.

Parameters:

  • obj

    (Dataref | Command) –

    Objet (Dataref or Command) to get the meta data for

  • force

    (bool, default: False ) –

    Force new fetch, do not read from cache (default: False)

Returns:

invalidate_caches 

invalidate_caches()

Remove cache data

rebuild_dataref_ids 

rebuild_dataref_ids()

Rebuild dataref idenfier index

reload_caches 

reload_caches(force: bool = False, save: bool = False)

Reload meta data caches

Must be performed regularly, if aircraft changed, etc.

Later, Laminar Research has plan for a notification of additing of datarefs

Parameters:

  • force

    (bool, default: False ) –

    Force reloading (default: False)

  • save

    (bool, default: False ) –

    Save raw meta data in JSON formatted files (default: False)

set_api_version 

set_api_version(api_version: str | None = None)

Set API version

Version is often specified with a v# short string. If no version is supplied, try to take the latest version available. Version numbering is not formally specified, ordering is performed using natural sorting. (See natsort.)

set_network 

set_network(host: str, port: int, api: str, api_version: str) -> bool

Set network and API parameters for connection

Parameters:

  • host

    (str) –

    Host name or IP address

  • port

    (int) –

    TCP port number for API

  • api

    (str) –

    API root path, starts with /.

  • api_version

    (str) –

    API version string, starts with /, appended to api string to form full path to API.

Returns:

  • bool ( bool ) –

    True if some network parameter has changed

set_roundings 

set_roundings(roundings)

Add rounding to simulator variable value. Rounding is applied to value before it is sent to callback function.

write_dataref 

write_dataref(dataref: Dataref) -> APIResult

Write single dataref value through REST API

Returns:

bool: success of operation