Core API: Difference between revisions

From Zaparoo Wiki

← Older edit
VisualWikitext
No edit summary
No edit summary
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Warn|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.}}
{{Warn|This API is not finalized. A version 1 release will be announced when it is ready for production. You're welcome to use the API as is, but be aware parts may breaking changes may still happen.}}


The TapTo API is an [[wikipedia:API|API]] available on and published by every device running the [[TapTo (Software)|core TapTo software]]. This API allows management of all TapTo features which would not present a security risk. The [https://tapto.life/ TapTo Life] app uses this API for all communication with TapTo devices, as does most of the arguments when TapTo is run via the CLI.
The '''Core API''' is available on and published by every device running the [[Zaparoo Core]] software. This API allows management of all Zaparoo features locally and remotely. The [https://zaparoo.app/ Zaparoo] app uses this API for all communication with Zaparoo devices, as do most of the flags when Zaparoo is run via the command line.


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.
This page documents the protocol used to communicate with the API and how to interact with it. ''It is currently the source of truth when developing applications that work with Zaparoo.''


== Communication Protocol ==
== 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.
The API uses a standard [https://developer.mozilla.org/en-US/docs/Web/API/WebSocket WebSocket] connection to exchange [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON JSON] payloads using the [https://www.jsonrpc.org/specification JSON-RPC 2.0] protocol. <!-- The secure layer protocol is not implemented yet. -->


All remote unsecured WebSocket connections must encrypt every payload using the secure layer detailed below, or else the payload will be immediately rejected. Local cleartext connections are allowed, depending on the platform and privilege context of the running service.
All remote cleartext WebSocket connections must encrypt every payload using the [[API#Secure Layer|secure layer]] detailed below, or else the payload will be rejected. Local unencrypted connections are allowed, depending on the platform and privilege context of the running service.


Communication follows a loose client-server relationship. Clients, by default, are not expected to implement the API beyond what that particular client needs to function.
Communication follows a loose client-server relationship. Clients, by default, are not expected to implement the API beyond what that particular client needs to function.


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


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


The connection requires no special configuration or authentication to begin.
The connection requires no special configuration or authentication to initiate.


=== JSON Payloads ===
=== JSON Payloads ===
Server and clients 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.
Server and clients communicate back and forth using JSON payloads, following the [https://www.jsonrpc.org/specification JSON-RPC 2.0] protocol.


Because a WebSocket connection is asynchronous, request payloads are tagged with a unique ID. The client must keep track of IDs sent to another client and wait for a matching response object.
Because a WebSocket connection is asynchronous, request payloads are tagged with a unique ID. The client must keep track of IDs sent to another client and wait for a matching response object. A client can continue sending requests while waiting for responses to previous requests.


==== Requests ====
==== Requests ====
A request object asks the connected server to run a pre-defined method, and report back when it's completed with a response object.
A request object asks the connected server to run a predefined [[API#Methods|method]], and report back when it's completed with a response object.


An example request:<syntaxhighlight lang="json">
An example request:<syntaxhighlight lang="json">
{
{
     "tapto": 1,
     "jsonrpc": "2.0",
     "id": "9ab7679f-6de9-11ef-9a9b-020304050607",
     "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "timestamp": 1725803556229,
     "method": "media.search",
     "method": "media.search",
     "params": {
     "params": {
Line 37: Line 36:
     }
     }
}
}
</syntaxhighlight>This request would query TapTo's media database for a file containing the word "240p" and return a response with the search results.
</syntaxhighlight>This request would query Zaparoo's media database for a filename containing the word "240p" and return a response with the search results.


Request keys:
===== Request object =====
{| class="wikitable"
{| class="wikitable"
|+
|+
Line 47: Line 46:
!Description
!Description
|-
|-
|tapto
|jsonrpc
|number
|string
|Yes
|Yes
|Specifies the protocol version and is used to validate a payload. It must be contained in every request or else the request will be rejected. Currently this must be the integer <code>1</code>.
|As per the JSON-RPC 2.0 spec, this key's value must be the string <code>2.0</code> for a payload to be accepted.
|-
|-
|id
|id
|string
|string
|Yes*
|Yes*
|A UUID v4 generated by the requesting client, used to match requests back to responses. A request missing this key is valid but would be treated as a notification and not receive any response (or an error).
|A UUID generated by the requesting client, used to match requests back to responses. A request missing this key is valid but would be treated as a notification and not receive any response.
|-
|timestamp
|number
|Yes
|An integer timestamp of the current UNIX epoch in milliseconds when the request was generated. This value is used by the secure layer to validate the request.
|-
|-
|method
|method
Line 72: Line 66:
|Arguments supplied for the method. The value of this key depends on the method used and is omitted for some methods.
|Arguments supplied for the method. The value of this key depends on the method used and is omitted for some methods.
|}
|}
All available request methods and their parameters are documented below.
All available request methods and their parameters are [[API#Methods|documented below]].


===== Notifications =====
==== Notifications ====
Notifications are requests which do not contain an ID. Otherwise, they are identical to a standard request object. Notifications can be sent by either server or client and do not receive a response.
Notifications are requests which do not contain an ID. Otherwise, they are identical to a standard request object. Notifications can be sent by either server or client and do not receive a response.


Like standard requests, notifications may or may not have parameters and its value will depend on the method. Types of notifications are documented below.
Like standard requests, notifications may or may not have parameters and its value will depend on the method. Types of notifications are [[API#Notifications|documented below]].


==== Responses ====
==== Responses ====
Every request sent must have a matching response. An example response to the media.search request shown above:<syntaxhighlight lang="json">
Every request sent must have a matching response. An example response to the media.search request shown above:<syntaxhighlight lang="json">
{
{
     "tapto": 1,
     "jsonrpc": "2.0",
     "id": "9ab7679f-6de9-11ef-9a9b-020304050607",
     "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "timestamp": 1725803557,
     "result": {
     "result": {
         "results": [{
         "media": [{
             "system": {
             "system": {
                 "id": "Gameboy",
                 "id": "Gameboy",
Line 97: Line 90:
     }
     }
}
}
</syntaxhighlight>Response keys:
</syntaxhighlight>
 
===== Response object =====
{| class="wikitable"
{| class="wikitable"
!Key
!Key
Line 104: Line 99:
!Description
!Description
|-
|-
|tapto
|jsonrpc
|number  
|number  
|Yes
|Yes
|Same as a request.
|Same as a [[API#Requests|request]].
|-
|-
|id
|id
|string
|string
|Yes
|Yes
|Same as a request. The same ID sent by the original request.
|Same as a [[API#Requests|request]]. The same ID sent by the original request.
|-
|timestamp
|number
|Yes
|Same as a request, with an updated time.
|-
|-
|result
|result
|any
|any
|No*
|No*
|Return value of the method. May be null depending on the method. See methods for possible values.
|Return value of the method. May be <code>null</code> depending on the method, will be missing if there was an error. See [[API#Methods|methods]] for possible values.
|-
|-
|error
|error
|Error
|Error
|No*
|No*
|If a method failed, this key will be populated with the error details and the result key will be empty. See below for details about errors.
|If a method failed, this key will be populated with the error details and the result key will be empty. See [[API#Response Errors|below]] for details about errors.
|}
|}


Line 133: Line 123:
If a method fails, it will populate the error key in the response object with details about the failure. An example of a failed request:<syntaxhighlight lang="json">
If a method fails, it will populate the error key in the response object with details about the failure. An example of a failed request:<syntaxhighlight lang="json">
{
{
     "tapto": 1,
     "jsonrpc": "2.0",
     "id": "9ab7679f-6de9-11ef-9a9b-020304050607",
     "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "timestamp": 1725805903,
     "error": {
     "error": {
         "code": 1,
         "code": 1,
Line 141: Line 130:
     }
     }
}
}
</syntaxhighlight>Error keys:
</syntaxhighlight>
 
===== Error object =====
{| class="wikitable"
{| class="wikitable"
!Key
!Key
Line 151: Line 142:
|number  
|number  
|Yes
|Yes
|An integer specifying the general error category. Error codes are not yet formalised.
|An integer specifying the general error category. '''Error codes are not yet formalised.'''
|-
|-
|message
|message
|string
|string
|Yes
|Yes
|Short human readable message explaining the error cause if possible.
|Short human readable message explaining the error cause, if possible.
|}
|}
==== Protocol Errors ====
==== Protocol Errors ====
If a low-level error occurs before a request context can be established, a protocol error will be sent back. This can happen, for example, if a JSON payload is malformed or a payload could not be decrypted. They're identical to an error response except they will have no ID.
If a low-level error occurs before a request context can be established, a protocol error will be sent back. This can happen, for example, if a JSON payload is malformed or a payload could not be decrypted. They're identical to an error response except they will have no ID.


Protocol errors may be sent cleartext if a secure context couldn't be established.
Protocol errors may be sent cleartext if a secure context couldn't be established, but will not contain any sensitive data.


=== Secure Layer ===
=== Secure Layer ===
The API supports a secure layer when communicating via an insecure WebSocket connection. This layer is required for all insecure remote WebSocket connections, and payloads will be rejected if not encrypted.
The API supports a secure layer when communicating via an cleartext WebSocket connection. This layer is required for all cleartext remote WebSocket connections, and payloads will be rejected if not encrypted.


Encryption is performed using AES256 and a shared secret key held by both server and client which is exchanged outside the API. Each payload sent must be encrypted by the sender and decrypted by the receiver. Responses must also be encrypted.
...
 
Be aware that although this process authenticates a client, TapTo does not currently enforce any type of role-based access. '''Any client with a valid secret key must be trusted with full access to the API.'''
 
An encrypted payload is in the format: <code>tapto:<client id>:<base64 encoded data></code>
 
The client ID is matched back to the TapTo service's internal database of IDs and associated secret keys. If there's a match, it will attempt to decrypt the encrypted data.
 
Clients are also managed through the API, but can only be done so via a device-local connection.
 
Each client must have accurate time set, as the timestamp is validated on the receiving server and checked against a history of payloads.


If a payload is decrypted successfully, it continues through the standard protocol process until the response which will be encrypted before sending back.
If a payload is decrypted successfully, it continues through the standard protocol process until the response which will be encrypted before sending back.


=== Anonymous Access ===
=== Anonymous Access ===
Anonymous cleartext access is, generally, allowed when an API connection is made from a loopback address (i.e. from the same device TapTo is running). This access depends on the platform and whether the service is running with elevated privileges. Check the page for the specific platform you're using to make sure it's available to you.
Anonymous cleartext access is, generally, allowed when an API connection is made from a loopback address (i.e. from the same device Zaparoo is running). This access depends on the platform and whether the service is running with elevated privileges. Check the page for the specific platform you're using to make sure it's available to you.


This access is also allowed when a connection is made over a WebSocket Secure (wss) connection.
This access is also allowed when a connection is made over a WebSocket Secure (wss) connection.


=== Launch Endpoint ===
=== Heartbeat ===
The HTTP server has one other endpoint which allows restricted access to trigger generic launch methods using a GET request. This endpoint is specifically meant to support uses such as QR codes scanned by a phone.
If sent the bytes <code>ping</code>, the API will immediately respond with the bytes <code>pong</code>. This feature can be used by heartbeat functions in WebSocket libraries.
 
== Launch Endpoint ==
The HTTP server has an additional endpoint which allows restricted access to launch [[ZapScript]] using a GET request. This endpoint is specifically meant to support uses such as QR codes scanned by a phone's camera app or simple launch testing.


The endpoint is: <code>/l/</code>
The endpoint is: <code>/l/</code>
Line 192: Line 176:
An example request: <code>GET <nowiki>http://10.0.0.123:7497/l/**launch.system:snes</nowiki></code>
An example request: <code>GET <nowiki>http://10.0.0.123:7497/l/**launch.system:snes</nowiki></code>


This would act as though a token with the text <code>**launch.system:snes</code> had been scanned, depending on this text being explicitly allowed in the config file.
This would act as though a token with the text <code>**launch.system:snes</code> had been scanned.
 
Requests from the local device are allowed without restriction. Remote requests must be explicitly allowed using the allow_launch config file setting.


== Methods ==
== Methods ==
Methods are used to execute actions and request data back from the API.
Methods are used to execute actions and request data back from the API. See the [[API/Methods|API Methods]] page for detailed definitions and examples of each method.
 
=== Launching ===
 
==== launch ====
Emulate the scanning of a token.
 
This method accepts two types of parameters:
 
* A single string, in which case the string will be treated as the token text with default launch options. Similar to the [[TapTo API#Launch Endpoint|Launch Endpoint]].
* Or a parameters object with the following keys:
 
{| class="wikitable"
{| class="wikitable"
!Key
|+
!Type
!ID
!Required
!Description
!Description
|-
|-
|type
|[[API/Methods#launch|launch]]
|string
|Emulate a token scan.
|No
|-
|An internal category of the type of token being scanned. Not currently in use outside of logging.
|[[API/Methods#stop|stop]]
|Kill any active launcher, if possible.
|-
|tokens
|List active tokens.
|-
|tokens.history
|Return a list of the latest token launches.
|-
|media
|Return status and statistics about media database.
|-
|media.active
|Return the currently active (now playing) media.
|-
|[[API/Methods#media.search|media.search]]
|Query the media database and return all matching indexed media.
|-
|-
|uid
|[[API/Methods#media.index|media.index]]
|string
|Start a new media database index.
|No*
|The UID of the token being scanner. For example, the UID of an NFC tag. Used for matching mappings.
|-
|-
|text
|[[API/Methods#systems|systems]]
|string
|List all currently indexed systems.
|No*
|The main text to be processed from a scan, should contain [[TapScript]].
|-
|-
|data
|[[API/Methods#settings 2|settings]]
|string
|List current configuration settings.
|No*
|The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys such as Amiibos and Lego Dimensions.
|}
These parameters allow emulating a token exactly as it would be read directly from an attached reader on the server. A request's parameters must contain at least a populated <code>uid</code>, <code>text</code> or <code>data</code> value.
 
This method does not have any response results. Currently, it is not reported if the launched TapScript encounters an error during launching.
 
==== stop ====
Kill any active launcher, if possible.
 
This methods takes no parameters and does not currently report whether it was successful or not.
 
==== history ====
 
=== Media ===
 
==== media.search ====
Query the media database and return all matching indexed media.
 
This request accepts the following parameters object:
{| class="wikitable"
!Key
!Type
!Required
!Description
|-
|-
|query
|[[API/Methods#settings.update|settings.update]]
|string
|Update one or more settings in-memory and save changes to disk.
|Yes
|Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
|-
|-
|system
|[[API/Methods#mappings 2|mappings]]
|string[]
|List all mappings.
|No
|Case-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems.
|-
|-
|maxResults
|[[API/Methods#mappings.new|mappings.new]]
|number
|Create a new mapping.
|No
|Max number of results to return. Default is 250.
|}
And a response with the following results object:
{| class="wikitable"
!Key
!Type
!Required
!Description
|-
|-
|results
|[[API/Methods#mappings.update|mappings.update]]
|Media[]  
|Change an existing mapping.
|Yes
|A list of all search results from the given query.
|-
|-
|total
|[[API/Methods#mappings.delete|mappings.delete]]
|number
|Delete an existing mapping.
|Yes
|Total number of search results.
|}
 
===== Media object =====
{| class="wikitable"
!Key
!Type
!Required
!Description
|-
|-
|system
|[[API/Methods#readers 2|readers]]
|System
|List all currently connected readers.
|Yes
|System which the media has been indexed under.
|-
|-
|name
|[[API/Methods#readers.write|readers.write]]
|string
|Attempt to write given text to the first available write-capable reader, if possible.
|Yes
|A human-readable version of the result's filename without a file extension.
|-
|-
|path
|[[API/Methods#clients 2|clients]]
|string
|List all clients (including disconnected) and associated data.
|Yes
|Path to the media file. If possible, this path will be compressed into the <code><system>/<path></code> launch format.
|}
 
===== System object =====
{| class="wikitable"
!Key
!Type
!Required
!Description
|-
|-
|id
|[[API/Methods#clients.new|clients.new]]
|string
|Create a new client with a newly generated ID and secret.
|Yes
|Internal system ID for this system.
|-
|-
|name
|[[API/Methods#clients.delete|clients.delete]]
|string
|Delete an existing client.
|Yes
|Display name of the system.
|-
|-
|category
|[[API/Methods#version|version]]
|string
|Return server's current version and platform.
|Yes
|Category of system. This field is not yet formalised.
|}
|}
==== media.index ====
Start a new media database index.


This method can, optionally, take a list of strings of system IDs to restrict the index to just those systems.
== Notifications ==
 
Notifications let a server or client know an event has occurred. See the [[API/Notifications|API Notifications]] page for detailed definitions and examples of each notification.
This method does not block and wait for the index to complete. It will return a response immediately and start in the background. <code>media.indexing</code> notifications will be sent to show progress of current indexing process.
 
==== systems ====
List all currently indexed systems.
 
This method has no parameters and returns a response results object of a list of [[TapTo API#System object|System objects]].
 
=== Settings ===
 
==== settings ====
List currently set configuration settings.
 
This method will list values set in the [[Config File (tapto.ini)|Config File]]. Values may be hidden which are not appropriate to be read remotely.
 
===== Parameters =====
This method has no parameters.
 
===== Results =====
{| class="wikitable"
{| class="wikitable"
!Key
|+
!Type
!ID
!Required
!Description
!Description
|-
|-
|reader
|launching
|string[]
|New ZapScript has been added to the launch queue.
|Yes
|A list of manually configured [[Reader Drivers|reader driver]] connection strings. See [[Config File (tapto.ini)#Manual Reader Connection (reader)|reader]].
|-
|audioFeedback
|boolean
|Yes
|
|-
|detectReaders
|boolean
|Yes
|
|-
|-
|insertMode
|readers.added
|boolean
|A new reader was connected to the server.
|Yes
|
|-
|-
|insertModeBlocklist
|readers.removed
|string[]
|A connected reader was disconnected from the server.
|Yes
|
|-
|-
|insertModeExitDelay
|tokens.added
|number
|A new token detected by a reader.
|Yes
|
|-
|-
|consoleLogging
|tokens.removed
|boolean
|A token was removed.
|Yes
|
|-
|-
|debug
|media.started
|boolean
|New media was started on server.
|Yes
|See [[Config File (tapto.ini)#Debug Logging (debug)|debug]].
|-
|-
|systems
|media.stopped
|Systems config
|Media has stopped on server.
|Yes
|The systems section of the config file.
|}
 
====== Systems config ======
{| class="wikitable"
!Key
!Type
!Required
!Description
|-
|-
|rootFolder
|media.indexing
|string[]
|The state of the indexing process has changed.
|Yes
|
|}
|}
====== API config ======
==== settings.update ====
Update one or more settings in-memory and save changes to disk.
=== Mappings ===
==== mappings ====
List all mappings.
Returns a list of all active and inactive mappings entries stored on server.
===== Parameters =====
===== Results =====
==== mappings.new ====
Create a new mapping.
===== Parameters =====
===== Results =====
==== mappings.delete ====
Delete an existing mapping.
===== Parameters =====
===== Results =====
==== mappings.update ====
Change an existing mapping.
===== Parameters =====
===== Results =====
=== Readers ===
==== readers ====
List all currently connected readers.
===== Parameters =====
===== Results =====
==== readers.write ====
Attempt to write given text to the first available write-capable reader, if possible.
===== Parameters =====
===== Results =====
=== Clients ===
''Clients can only be managed through the API via a device-local connection.''
==== clients ====
List all clients (including disconnected) and associated data.
==== clients.new ====
Create a new client with a newly generated ID and secret.
==== clients.delete ====
Delete an existing client.
=== Service ===
==== version ====
Return server's current version and platform.
== Notifications ==
Notifications let a server or client know an event has occurred.
=== Reader ===
==== readers.connected ====
A new reader was connected to the server.
==== readers.disconnected ====
A connected reader was disconnected from the server.
=== Tokens ===
==== tokens.launching ====
A new token was added to the launch queue.
==== tokens.active ====
The state of the currently active token has changed.
=== Media ===
==== media.started ====
New media was started on server.
==== media.stopped ====
Media has stopped on server.
==== media.indexing ====
The state of the indexing process has changed.

Latest revision as of 06:18, 24 December 2024

This API is not finalized. A version 1 release will be announced when it is ready for production. You're welcome to use the API as is, but be aware parts may breaking changes may still happen.

The Core API is available on and published by every device running the Zaparoo Core software. This API allows management of all Zaparoo features locally and remotely. The Zaparoo app uses this API for all communication with Zaparoo devices, as do most of the flags when Zaparoo is run via the command line.

This page documents the protocol used to communicate with the API and how to interact with it. It is currently the source of truth when developing applications that work with Zaparoo.

Communication Protocol

The API uses a standard WebSocket connection to exchange JSON payloads using the JSON-RPC 2.0 protocol.

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

Communication follows a loose client-server relationship. Clients, by default, are not expected to implement the API beyond what that particular client needs to function.

Connection

Connections to the API can be established with any standard WebSocket client, using the root endpoint (/) of the HTTP server published by the Zaparoo service. By default, the HTTP server is accessible on port 7497. 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 initiate.

JSON Payloads

Server and clients communicate back and forth using JSON payloads, following the JSON-RPC 2.0 protocol.

Because a WebSocket connection is asynchronous, request payloads are tagged with a unique ID. The client must keep track of IDs sent to another client and wait for a matching response object. A client can continue sending requests while waiting for responses to previous requests.

Requests

A request object asks the connected server to run a predefined method, and report back when it's completed with a response object.

An example request:

{
    "jsonrpc": "2.0",
    "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "method": "media.search",
    "params": {
        "query": "240p"
    }
}

This request would query Zaparoo's media database for a filename containing the word "240p" and return a response with the search results.

Request object
Key Type Required Description
jsonrpc string Yes As per the JSON-RPC 2.0 spec, this key's value must be the string 2.0 for a payload to be accepted.
id string Yes* A UUID generated by the requesting client, used to match requests back to responses. A request missing this key is valid but would be treated as a notification and not receive any response.
method string Yes A string corresponding to a method to be run by the receiving server.
params any No Arguments supplied for the method. The value of this key depends on the method used and is omitted for some methods.

All available request methods and their parameters are documented below.

Notifications

Notifications are requests which do not contain an ID. Otherwise, they are identical to a standard request object. Notifications can be sent by either server or client and do not receive a response.

Like standard requests, notifications may or may not have parameters and its value will depend on the method. Types of notifications are documented below.

Responses

Every request sent must have a matching response. An example response to the media.search request shown above:

{
    "jsonrpc": "2.0",
    "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "result": {
        "media": [{
            "system": {
                "id": "Gameboy",
                "name": "Gameboy"
            },
            "name": "240p Test Suite (PD) v0.03 tepples",
            "path": "Gameboy/240p Test Suite (PD) v0.03 tepples.gb"
        }],
        "total": 1
    }
}
Response object
Key Type Required Description
jsonrpc number Yes Same as a request.
id string Yes Same as a request. The same ID sent by the original request.
result any No* Return value of the method. May be null depending on the method, will be missing if there was an error. See methods for possible values.
error Error No* If a method failed, this key will be populated with the error details and the result key will be empty. See below for details about errors.
Response Errors

If a method fails, it will populate the error key in the response object with details about the failure. An example of a failed request:

{
    "jsonrpc": "2.0",
    "id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
    "error": {
        "code": 1,
        "message": "query or system is required"
    }
}
Error object
Key Type Required Description
code number Yes An integer specifying the general error category. Error codes are not yet formalised.
message string Yes Short human readable message explaining the error cause, if possible.

Protocol Errors

If a low-level error occurs before a request context can be established, a protocol error will be sent back. This can happen, for example, if a JSON payload is malformed or a payload could not be decrypted. They're identical to an error response except they will have no ID.

Protocol errors may be sent cleartext if a secure context couldn't be established, but will not contain any sensitive data.

Secure Layer

The API supports a secure layer when communicating via an cleartext WebSocket connection. This layer is required for all cleartext remote WebSocket connections, and payloads will be rejected if not encrypted.

...

If a payload is decrypted successfully, it continues through the standard protocol process until the response which will be encrypted before sending back.

Anonymous Access

Anonymous cleartext access is, generally, allowed when an API connection is made from a loopback address (i.e. from the same device Zaparoo is running). This access depends on the platform and whether the service is running with elevated privileges. Check the page for the specific platform you're using to make sure it's available to you.

This access is also allowed when a connection is made over a WebSocket Secure (wss) connection.

Heartbeat

If sent the bytes ping, the API will immediately respond with the bytes pong. This feature can be used by heartbeat functions in WebSocket libraries.

Launch Endpoint

The HTTP server has an additional endpoint which allows restricted access to launch ZapScript using a GET request. This endpoint is specifically meant to support uses such as QR codes scanned by a phone's camera app or simple launch testing.

The endpoint is: /l/

An example request: GET http://10.0.0.123:7497/l/**launch.system:snes

This would act as though a token with the text **launch.system:snes had been scanned.

Requests from the local device are allowed without restriction. Remote requests must be explicitly allowed using the allow_launch config file setting.

Methods

Methods are used to execute actions and request data back from the API. See the API Methods page for detailed definitions and examples of each method.

ID Description
launch Emulate a token scan.
stop Kill any active launcher, if possible.
tokens List active tokens.
tokens.history Return a list of the latest token launches.
media Return status and statistics about media database.
media.active Return the currently active (now playing) media.
media.search Query the media database and return all matching indexed media.
media.index Start a new media database index.
systems List all currently indexed systems.
settings List current configuration settings.
settings.update Update one or more settings in-memory and save changes to disk.
mappings List all mappings.
mappings.new Create a new mapping.
mappings.update Change an existing mapping.
mappings.delete Delete an existing mapping.
readers List all currently connected readers.
readers.write Attempt to write given text to the first available write-capable reader, if possible.
clients List all clients (including disconnected) and associated data.
clients.new Create a new client with a newly generated ID and secret.
clients.delete Delete an existing client.
version Return server's current version and platform.

Notifications

Notifications let a server or client know an event has occurred. See the API Notifications page for detailed definitions and examples of each notification.

ID Description
launching New ZapScript has been added to the launch queue.
readers.added A new reader was connected to the server.
readers.removed A connected reader was disconnected from the server.
tokens.added A new token detected by a reader.
tokens.removed A token was removed.
media.started New media was started on server.
media.stopped Media has stopped on server.
media.indexing The state of the indexing process has changed.
Retrieved from "https://wiki.zaparoo.org/index.php?title=Core_API&oldid=683"