Development:API

Documentation of the current implementation of the API used between Zaparoo and Zaparoo. 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 supported systems list used by the MiSTer Extensions project, the various computer and console systems supported by MiSTer. Zaparoo 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.

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

REST

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

Status

Get the current overall status of various parts of the Zaparoo service.

GET /status

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

Response

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

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

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	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

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

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

curl --request GET --url "http://10.0.0.107:7497/api/v1/status"

Response

{
  "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"
  }
}

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)

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	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

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

Response