Core API

This page refers to the future version 2.0.0 of TapTo which is in active development. Please don't use any information on this page until it's been finalised and released.

The TapTo API is an API available on and published by every device running the core TapTo software. This API allows management of all TapTo features which would not present a security risk. The TapTo Life app uses this API for all communication with TapTo devices.

This page documents the protocol used to communicate with the API and each method available to interact with a TapTo device. It is the source of truth when developing applications that interact with TapTo.

Communication Protocol

The API uses a standard WebSocket connection to exchange JSON payloads using a custom variant of the JSON-RPC 2.0 protocol. It is not compatible with standard JSON-RPC libraries.

All remote unsecured WebSocket connections must encrypt every payload using the encryption layer detailed below, or else the payload will be immediately rejected. Local unencrypted connections are allowed, depending on the platform and privilege context of the running service.

Connection

Connections to the API can be established with any standard WebSocket client, using the root endpoint (/) of the HTTP server published by the TapTo service. By default, the HTTP server is accessible on port 7497. Keep in mind this port is configurable by the user.

An example address for connecting to the API: ws://10.0.0.123:7497/

The connection requires no special configuration or authentication to begin.

JSON Payloads

Peers communicate back and forth using JSON payloads and a request-response based on the JSON-RPC 2.0 protocol. The TapTo protocol is incompatible with existing JSON-RPC libraries.

Because a WebSocket connection is asynchronous, request payloads are tagged with a unique ID. The client peer must keep track of IDs sent to another client and wait for a matching response object.

Requests

A request object informs the peer to run a pre-defined method, and report back when it's completed with a response object.