API/Methods: Difference between revisions

From Zaparoo Wiki

< API

m Text replacement - "TapScript" to "ZapScript"
 
(4 intermediate revisions by the same user not shown)
Line 31: Line 31:
|string
|string
|No*
|No*
|The main text to be processed from a scan, should contain [[TapScript]].
|The main text to be processed from a scan, should contain [[ZapScript]].
|-
|-
|data
|data
Line 43: Line 43:
Returns <code>null</code> on success.
Returns <code>null</code> on success.


Currently, it is not reported if the launched TapScript encountered an error during launching, and the method will return before execution of TapScript is complete.
Currently, it is not reported if the launched ZapScript encountered an error during launching, and the method will return before execution of ZapScript is complete.


==== Example ====
==== Example ====
Line 69: Line 69:
</syntaxhighlight>
</syntaxhighlight>


=== launch.history ===
=== stop ===
Kill any active launcher, if possible.
 
This method is highly dependant on the platform and specific launcher used. It's not guaranteed that a launcher is capable of killing the playing process.
 
==== Parameters ====
None.
 
==== Result ====
Returns <code>null</code> on success.
 
Currently, it is not reported if a process was killed or not.
 
==== Example ====
 
===== Request =====
<syntaxhighlight lang="json">
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "method": "stop"
}
 
</syntaxhighlight>
 
===== Response =====
<syntaxhighlight lang="json">
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "result": null
}
 
</syntaxhighlight>
 
== Tokens ==
 
=== tokens.history ===
Returns a list of the last recorded token launches.
Returns a list of the last recorded token launches.


Line 83: Line 120:
|-
|-
|entries
|entries
|LaunchEntry[]  
|[[API/Methods#Launch entry object|LaunchEntry]][]  
|Yes
|Yes
|A list of recorded token launches.
|A list of recorded token launches.
Line 155: Line 192:
         ]
         ]
     }
     }
}
</syntaxhighlight>
=== stop ===
Kill any active launcher, if possible.
This method is highly dependant on the platform and specific launcher used. It's not guaranteed that a launcher is capable of killing the playing process.
==== Parameters ====
None.
==== Result ====
Returns <code>null</code> on success.
Currently, it is not reported if a process was killed or not.
==== Example ====
===== Request =====
<syntaxhighlight lang="json">
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "method": "stop"
}
</syntaxhighlight>
===== Response =====
<syntaxhighlight lang="json">
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "result": null
}
}


Line 212: Line 214:
|Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
|Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
|-
|-
|system
|systems
|string[]
|string[]
|No
|No
Line 635: Line 637:


== Mappings ==
== Mappings ==
Mappings are used to modify the contents of tokens before they're launched, based on different types of matching parameters. Stored mappings are queried before every launch and applied to the token if there's a match. This allows, for example, adding TapScript to a read-only NFC tag based on its UID.
Mappings are used to modify the contents of tokens before they're launched, based on different types of matching parameters. Stored mappings are queried before every launch and applied to the token if there's a match. This allows, for example, adding ZapScript to a read-only NFC tag based on its UID.


=== mappings ===
=== mappings ===
Line 688: Line 690:
|string
|string
|Yes
|Yes
|The method used to match a mapping pattern:
|The field which will be matched against:


* <code>exact</code>: match the entire string exactly to the field.
* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>partial</code>: match part of the string to the field.
* <code>text</code>: match on the stored text on token.
* <code>regex</code>: use a regular expression to match the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
|-
|-
|match
|match
|string
|string
|Yes
|Yes
|The field which will be matched against:
|The method used to match a mapping pattern:


* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>exact</code>: match the entire string exactly to the field.
* <code>text</code>: match on the stored text on token.
* <code>partial</code>: match part of the string to the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
* <code>regex</code>: use a regular expression to match the field.
|-
|-
|pattern
|pattern
Line 773: Line 775:
|string
|string
|Yes
|Yes
|The method used to match a mapping pattern:
|The field which will be matched against:


* <code>exact</code>: match the entire string exactly to the field.
* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>partial</code>: match part of the string to the field.
* <code>text</code>: match on the stored text on token.
* <code>regex</code>: use a regular expression to match the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
|-
|-
|match
|match
|string
|string
|Yes
|Yes
|The field which will be matched against:
|The method used to match a mapping pattern:


* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>exact</code>: match the entire string exactly to the field.
* <code>text</code>: match on the stored text on token.
* <code>partial</code>: match part of the string to the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
* <code>regex</code>: use a regular expression to match the field.
|-
|-
|pattern
|pattern
Line 864: Line 866:
|string
|string
|No
|No
|The method used to match a mapping pattern:
|The field which will be matched against:


* <code>exact</code>: match the entire string exactly to the field.
* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>partial</code>: match part of the string to the field.
* <code>text</code>: match on the stored text on token.
* <code>regex</code>: use a regular expression to match the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
|-
|-
|match
|match
|string
|string
|No
|No
|The field which will be matched against:
|The method used to match a mapping pattern:


* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
* <code>exact</code>: match the entire string exactly to the field.
* <code>text</code>: match on the stored text on token.
* <code>partial</code>: match part of the string to the field.
* <code>data</code>: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
* <code>regex</code>: use a regular expression to match the field.
|-
|-
|pattern
|pattern
Line 936: Line 938:
|string
|string
|Yes
|Yes
|TapScript to be written to the token.
|ZapScript to be written to the token.
|}
|}


Line 1,077: Line 1,079:
|string
|string
|Yes
|Yes
|Current version of the running TapTo service.
|Current version of the running Zaparoo service.
|}
|}



Latest revision as of 00:12, 30 November 2024

Methods are used to execute actions and request data back from the API.

Launching

launch

Emulate the scanning of a token.

Parameters

Accepts two types of parameters:

  • A string, in which case the string will be treated as the token text with all other options set as default.
  • An object:
Key Type Required Description
type string No An internal category of the type of token being scanned. Not currently in use outside of logging.
uid string No* The UID of the token being scanned. For example, the UID of an NFC tag. Used for matching mappings.
text string No* The main text to be processed from a scan, should contain ZapScript.
data string No* The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys.

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 uid, text or data value.

Result

Returns null on success.

Currently, it is not reported if the launched ZapScript encountered an error during launching, and the method will return before execution of ZapScript is complete.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "52f6242e-7a5a-11ef-bf93-020304050607",
    "method": "launch",
    "params": {
        "text": "**launch.system:snes"
    }
}
Response
{
    "jsonrpc": "2.0",
    "id": "52f6242e-7a5a-11ef-bf93-020304050607",
    "result": null
}

stop

Kill any active launcher, if possible.

This method is highly dependant on the platform and specific launcher used. It's not guaranteed that a launcher is capable of killing the playing process.

Parameters

None.

Result

Returns null on success.

Currently, it is not reported if a process was killed or not.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "method": "stop"
}
Response
{
    "jsonrpc": "2.0",
    "id": "176b4558-7a5b-11ef-b318-020304050607",
    "result": null
}

Tokens

tokens.history

Returns a list of the last recorded token launches.

Parameters

None.

Result

Key Type Required Description
entries LaunchEntry[] Yes A list of recorded token launches.
Launch entry object
Key Type Required Description
data string No Same as launch parameter.
success boolean Yes True if the launch was successful.
text string No Same as launch parameter.
time string Yes Timestamp of the launch time in RFC3339 format.
type string No Same as launch parameter.
uid string No Same as launch parameter.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "5e9f3a0e-7a5b-11ef-8084-020304050607",
    "method": "history"
}
Response
{
    "jsonrpc": "2.0",
    "id": "5e9f3a0e-7a5b-11ef-8084-020304050607",
    "result": {
        "entries": [
            {
                "data": "",
                "success": true,
                "text": "**launch.system:snes",
                "time": "2024-09-24T17:49:42.938167429+08:00",
                "type": "",
                "uid": ""
            }
        ]
    }
}

Media

media.search

Query the media database and return all matching indexed media.

Parameters

An object:

Key Type Required Description
query string Yes Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
systems string[] No Case-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems.
maxResults number No Max number of results to return. Default is 250.

Result

Key Type Required Description
results Media[] Yes A list of all search results from the given query.
total number Yes Total number of search results.
Media object
Key Type Required Description
system System Yes System which the media has been indexed under.
name string Yes A human-readable version of the result's filename without a file extension.
path string Yes Path to the media file. If possible, this path will be compressed into the <system>/<path> launch format.
System object
Key Type Required Description
id string Yes Internal system ID for this system.
name string Yes Display name of the system.
category string Yes Category of system. This field is not yet formalised.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "47f80537-7a5d-11ef-9c7b-020304050607",
    "method": "media.search",
    "params": {
        "query": "240p"
    }
}
Response
{
    "jsonrpc": "2.0",
    "id": "47f80537-7a5d-11ef-9c7b-020304050607",
    "result": {
        "results": [
            {
                "name": "240p Test Suite (PD) v0.03 tepples",
                "path": "Gameboy/240p Test Suite (PD) v0.03 tepples.gb",
                "system": {
                    "category": "Handheld",
                    "id": "Gameboy",
                    "name": "Gameboy"
                }
            }
        ],
        "total": 1
    }
}

media.index

Create a new media database index.

During an index, the server will emit media.indexing notifications showing progress of the index.

Parameters

Optionally, an object:

Key Type Required Description
systems string[] No List of system IDs to restrict indexing to. Other system indexes will remain as is.

An omitted or null value parameters key is also valid and will index every system.

Result

Returns null on success once indexing is complete.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "6f20e07c-7a5e-11ef-84bb-020304050607",
    "method": "media.index"
}
Response
{
    "jsonrpc": "2.0",
    "id": "6f20e07c-7a5e-11ef-84bb-020304050607",
    "result": null
}

systems

List all currently indexed systems.

Parameters

None.

Result

Key Type Required Description
systems System[] Yes A list of all indexed systems.

See system object.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "dbd312f3-7a5f-11ef-8f29-020304050607",
    "method": "systems"
}
Response
{
    "jsonrpc": "2.0",
    "id": "dbd312f3-7a5f-11ef-8f29-020304050607",
    "result": {
        "systems": [
            {
                "category": "Handheld",
                "id": "GameboyColor",
                "name": "Gameboy Color"
            },
            {
                "category": "Computer",
                "id": "EDSAC",
                "name": "EDSAC"
            }
        ]
    }
}

Settings

settings

List currently set configuration settings.

This method will list values set in the Config File. Some config file options may be omitted which are not appropriate to be read or written remotely.

Parameters

None.

Result

Key Type Required Description
reader string[] Yes A list of manually configured reader driver connection strings. See reader.
audioFeedback boolean Yes
detectReaders boolean Yes
insertMode boolean Yes
insertModeBlocklist string[] Yes
insertModeExitDelay number Yes
consoleLogging boolean Yes
debug boolean Yes See debug.
systems Systems config Yes The systems section of the config file.
Systems config
Key Type Required Description
rootFolder string[] Yes

Example

Request
{
    "jsonrpc": "2.0",
    "id": "f208d996-7ae6-11ef-960e-020304050607",
    "method": "settings"
}
Response
{
    "jsonrpc": "2.0",
    "id": "f208d996-7ae6-11ef-960e-020304050607",
    "result": {
        "readers": ["pn532_uart:/dev/ttyUSB0"],
        "detectReaders": true,
        "audioFeedback": true,
        "insertMode": false,
        "insertModeBlocklist": ["DOS"],
        "insertModeExitDelay": 0,
        "consoleLogging": false,
        "debug": false,
        "systems": {
            "rootFolders": []
        }
    }
}

settings.update

Update one or more settings in-memory and save changes to disk.

This method will only write values which are supplied. Existing values will not be modified.

Parameters

An object:

Key Type Required Description
reader string[] Yes A list of manually configured reader driver connection strings. See reader.
audioFeedback boolean Yes
detectReaders boolean Yes
insertMode boolean Yes
insertModeBlocklist string[] Yes
insertModeExitDelay number Yes
consoleLogging boolean Yes
debug boolean Yes See debug.
systems Systems config Yes The systems section of the config file.
Systems config
Key Type Required Description
rootFolder string[] Yes

Result

Returns null on success.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "562c0b60-7ae8-11ef-87d7-020304050607",
    "method": "settings.update",
    "params": {
        "debug": false
    }
}
Response
{
    "jsonrpc": "2.0",
    "id": "562c0b60-7ae8-11ef-87d7-020304050607",
    "result": null
}

Mappings

Mappings are used to modify the contents of tokens before they're launched, based on different types of matching parameters. Stored mappings are queried before every launch and applied to the token if there's a match. This allows, for example, adding ZapScript to a read-only NFC tag based on its UID.

mappings

List all mappings.

Returns a list of all active and inactive mappings entries stored on server.

Parameters

None.

Result

Key Type Required Description
mappings Mapping[] Yes List of all stored mappings. See mapping object.
Mapping object
Key Type Required Description
added string Yes Timestamp of the time mapping was created in RFC3339 format.
enabled boolean Yes True if the mapping will be used when looking up matching mappings.
id number Yes Internal database ID of mapping entry. Used to reference mapping for updates and deletions.
label string No An optional display name shown to the user.
type string Yes The field which will be matched against:
  • uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
  • text: match on the stored text on token.
  • data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
match string Yes The method used to match a mapping pattern:
  • exact: match the entire string exactly to the field.
  • partial: match part of the string to the field.
  • regex: use a regular expression to match the field.
pattern string Yes Pattern that will be matched against the token, using the above settings.
override string Yes Final text that will completely replace the existing token text if a match was successful.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "1a8bee28-7aef-11ef-8427-020304050607",
    "method": "mappings"
}
Response
{
    "jsonrpc": "2.0",
    "id": "1a8bee28-7aef-11ef-8427-020304050607",
    "result": {
        "mappings": [
            {
                "added": "1970-01-21T06:08:18+08:00",
                "enabled": true,
                "id": "1",
                "label": "barcode pokemon",
                "match": "partial",
                "override": "**launch.search:gbc/*pokemon*gold*",
                "pattern": "9780307468031",
                "type": "text"
            }
        ]
    }
}

mappings.new

Create a new mapping.

Parameters

An object:

Key Type Required Description
enabled boolean Yes True if the mapping will be used when looking up matching mappings.
label string No An optional display name shown to the user.
type string Yes The field which will be matched against:
  • uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
  • text: match on the stored text on token.
  • data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
match string Yes The method used to match a mapping pattern:
  • exact: match the entire string exactly to the field.
  • partial: match part of the string to the field.
  • regex: use a regular expression to match the field.
pattern string Yes Pattern that will be matched against the token, using the above settings.
override string Yes Final text that will completely replace the existing token text if a match was successful.

Result

Key Type Required Description
id number Yes Database ID of new mapping entry.

Example

mappings.delete

Delete an existing mapping.

Parameters

Key Type Required Description
id number Yes Database ID of mapping.

Result

Returns null on success.

Example

mappings.update

Change an existing mapping.

Parameters

An object:

Key Type Required Description
id number Yes Internal database ID of mapping entry.
enabled boolean No True if the mapping will be used when looking up matching mappings.
label string No An optional display name shown to the user.
type string No The field which will be matched against:
  • uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
  • text: match on the stored text on token.
  • data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
match string No The method used to match a mapping pattern:
  • exact: match the entire string exactly to the field.
  • partial: match part of the string to the field.
  • regex: use a regular expression to match the field.
pattern string No Pattern that will be matched against the token, using the above settings.
override string No Final text that will completely replace the existing token text if a match was successful.

Only keys which are provided in the object will be updated in the database.

Result

Returns null on success.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "e98fd686-7e62-11ef-8f8c-020304050607",
    "method": "mappings.update",
    "params": {
        "enabled": false,
        "id": 1
    }
}
Result

Readers

readers

List all currently connected readers.

Parameters

Result

Example

readers.write

Attempt to write given text to the first available write-capable reader, if possible.

Parameters

An object:

Key Type Required Description
text string Yes ZapScript to be written to the token.

Result

Returns null on success.

Example

Clients

Clients can only be managed through the API via a device-local connection.

clients

List all registered clients and associated data.

Parameters

None.

Result

Key Type Required Description
clients Client[] Yes List of all registered clients.
Client object
Key Type Required Description
id string Yes Unique ID of client.
name string No Display name of client.
secret string Yes Secret key of client.
address string No Last connected address of client.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
    "method": "clients"
}
Response
{
    "jsonrpc": "2.0",
    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
    "result": {
        "clients": [
            {
                "address": "",
                "id": "0b150eae-0f1b-4ede-9d7c-09c0ae0509ea",
                "name": "Test",
                "secret": "d3edfd14ce20e64f01c06932dcb5553560d0995a8871b7398c9a7b7fcc42e670"
            }
        ]
    }
}

clients.new

Create a new client with a newly generated ID and secret.

Parameters

Optionally, an object:

Key Type Required Description
name string No Display name of client.

Result

Example

clients.delete

Delete an existing client.

Parameters

Result

Example

Service

version

Return server's current version and platform.

Parameters

None.

Result

Key Type Required Description
platform string Yes ID of platform the service is currently running on.
version string Yes Current version of the running Zaparoo service.

Example

Request
{
    "jsonrpc": "2.0",
    "id": "ca47f646-7e47-11ef-971a-020304050607",
    "method": "version"
}
Response
{
    "jsonrpc": "2.0",
    "id": "ca47f646-7e47-11ef-971a-020304050607",
    "result": {
        "platform": "mister",
        "version": "2.0.0-dev"
    }
}