View source for Development:API

Documentation of the current implementation of the API used between [[TapTo (Software)|TapTo]] and [[TapTo Life]]. The API is mainly a REST API, but also implements a separate WebSocket API for certain functions that work better in real time (like tracking the current played game).

When this documentation refers to a "system ID" it is talking about the [https://github.com/wizzomafizzo/mrext/blob/main/docs/systems.md supported systems list] used by the [https://github.com/wizzomafizzo/mrext/ MiSTer Extensions] project, the various computer and console systems supported by MiSTer. TapTo will eventually fork this list of system definitions, so it can be expanded beyond MiSTer supporter systems. Existing system IDs will remain the same to preserve backward compatibility or kept as aliases.

{{Warn|This API is not finalized. Please don't implement anything using it yet without expecting breaking changes.}}

== REST ==
The REST API is accessible at <code>http://[IP/hostname]:7497/api/v1</code> and can be used with any standard HTTP client such as [https://curl.se/ curl], which is used for all examples.

==== Status ====
Get the current overall status of various parts of the TapTo service.

<code>GET /status</code>

On success, returns 200 and an object containing the state of various parts of the TapTo service.

===== Response =====
{| class="wikitable"
|+
!Attribute
!Type
!Description
|-
|reader
|Reader
|Current physically connected NFC reader.
|-
|activeToken
|Token
|Token that is currently in contact with the reader or recently in contact if in tap mode.
|-
|lastToken
|Token
|Last scanned token either by a reader or launched through the API.
|-
|gamesIndex
|Games Index
|Current status of the host device's games index/database.
|-
|playing
|Playing
|Game currently active on the host device.
|}

====== Reader ======
{| class="wikitable"
|+
!Attribute
!Type
!Description
|-
|connected
|boolean
|If there is a physical NFC reader attached to the host device and successfully connected.
|-
|type
|string
|Model of detected NFC reader: PN532, ACR122U or Unknown
|}

====== Token ======
{| class="wikitable"
|+
!Attribute
!Type
!Description
|-
|type
|string
|Type of token that was scanned: NTAG, MIFARE, Amiibo, LegoDimensions or __api__ (if launching a virtual token over this API) 
|-
|uid
|string
|Unique physical ID assigned to an NFC tag. May be blank.
|-
|text
|string
|[[Token Commands|Command text]] contained on a token. May be blank.
|-
|data
|string
|Relevant raw bytes (in hexadecimal format) contained on an NFC tag. May be blank.
|-
|scanTime
|string
|Date and time that this token was scanned. Example: 2024-05-09T19:30:01.317137397+08:00
|}

====== Games Index ======
{| class="wikitable"
|+
!Attribute
!Type
!Description
|-
|exists
|boolean
|True if the games index/database has been created.
|-
|indexing
|boolean
|True if an games index is currently in progress.
|-
|totalSteps
|number
|Total number of "steps" in indexing process. Used to show progress to user, currently splits indexing by system.
|-
|currentStep
|number
|Active step in indexing process.
|-
|currectDesc
|string
|Human readable description of current step.
|-
|totalFiles
|number
|A running tally of total files indexed by process. Resets at end of index.
|}

====== Playing ======
{| class="wikitable"
|+
!Attribute
!Type
!Description
|-
|system
|string
|Internal system ID of the active game.
|-
|systemName
|string
|Human readable name of the system of the active game.
|-
|game
|string
|Internal ID of the active game.
|-
|gameName
|string
|Human readable name of the active game.
|-
|gamePath
|string
|Path on disk to active game, formatted to as a valid launcher for a token.
|}

===== Examples =====

====== Request ======
<code>curl --request GET --url "<nowiki>http://10.0.0.107:7497/api/v1/status</nowiki>"</code>

====== Response ======
<syntaxhighlight lang="json">
{
  "reader":{
    "connected":true,
    "type":"PN532"
  },
  "activeToken":{
    "type":"NTAG",
    "uid":"04df1f02615780",
    "text":"Genesis/@Genesis - MegaSD Mega EverDrive Game Series Collections 2022-05-18.zip/4 Game Series Collections/Sega - Genesis Mini/Columns (USA, Europe).md",
    "data":"039dd101995402656e47656e657369732f4047656e65736973202d204d6567615344204d656761204576657244726976652047616d652053657269657320436f6c6c656374696f6e7320323032322d30352d31382e7a69702f342047616d652053657269657320436f6c6c656374696f6e732f53656761202d2047656e65736973204d696e692f436f6c756d6e7320285553412c204575726f7065292e6d64fe",
    "scanTime":"2024-05-09T19:30:01.317137397+08:00"
  },
  "lastToken":{
    "type":"NTAG",
    "uid":"04df1f02615780",
    "text":"Genesis/@Genesis - MegaSD Mega EverDrive Game Series Collections 2022-05-18.zip/4 Game Series Collections/Sega - Genesis Mini/Columns (USA, Europe).md",
    "data":"039dd101995402656e47656e657369732f4047656e65736973202d204d6567615344204d656761204576657244726976652047616d652053657269657320436f6c6c656374696f6e7320323032322d30352d31382e7a69702f342047616d652053657269657320436f6c6c656374696f6e732f53656761202d2047656e65736973204d696e692f436f6c756d6e7320285553412c204575726f7065292e6d64fe",
    "scanTime":"2024-05-09T19:30:01.317137397+08:00"
  },
  "launching":true,
  "gamesIndex":{
    "exists":true,
    "indexing":false,
    "totalSteps":0,
    "currentStep":0,
    "currentDesc":"",
    "totalFiles":0
  },
  "playing":{
    "system":"Genesis",
    "systemName":"Genesis",
    "game":"Genesis/Columns (USA, Europe).md",
    "gameName":"Columns (USA, Europe)",
    "gamePath":"Genesis/@Genesis - MegaSD Mega EverDrive Game Series Collections 2022-05-18.zip/4 Game Series Collections/Sega - Genesis Mini/Columns (USA, Europe).md"
  }
}
</syntaxhighlight>

==== Launch ====

===== Launch a token =====
Launch a custom token, with options to imitate a physical NFC tag.

POST /launch

On success, returns 200. Launches are queued asynchronously, any errors raised during launch will not be reported in return value.

Arguments (JSON)
{| class="wikitable"
|+
!Attribute
!Type
!Required
!Description
|-
|type
|string
|Yes
|Hardware type of token: NTAG, MIFARE, Amiibo or LegoDimensions
|-
|uid
|string
|Yes
|Unique physical ID assigned to an NFC tag. May be blank.
|-
|text
|string
|Yes
|[[Token Commands|Command text]] contained on a token. May be blank.
|-
|data
|string
|Yes
|Relevant raw bytes (in hexadecimal format) contained on an NFC tag. May be blank.
|}
Response

None.

Examples

Request

<code>curl --request POST --url "http://10.0.0.107:7497/api/v1/launch" --data '{}'</code>

Response

===== Launch a basic token =====

===== Exit the current game =====

==== Readers ====

===== Write a tag using physical NFC reader =====

==== Games ====

===== Search for games =====

==== Systems ====

===== List indexed systems =====

==== Mappings ====

===== List all mappings =====

===== Add a new mapping =====

===== Delete an existing mapping =====

===== Update an existing mapping =====

==== History ====

===== List latest scan history =====

==== Settings ====

===== View all service settings =====

===== Update service settings =====

== WebSocket ==