About RetroDECK API Development

The RetroDECK API enables external applications to access information and perform actions through the RetroDECK Framework, allowing them to function as the RetroDECK Configurator.

Currently, the API is accessible only via named pipes or internally within the RetroDECK Framework. Additional communication methods may be introduced in the future.

API Request Index

Request Group: DO

Request Group: GET

Request Group: SET

Communication with the API

If you would like to communicate with the RetroDECK API, follow this process:

If RetroDECK is not currently running, the API server can be started by using the command: flatpak run net.retrodeck.retrodeck --api
If RetroDECK is currently running, the server should already be started. This can be validated by looking for this specific named pipe: ~/.var/app/net.retrodeck.retrodeck/config/retrodeck/api/retrodeck_api_pipe

This is the "listening" pipe used by the API, and all requests will enter the system through this pipe.

The client making the request must then generate a unique (but arbitrary) "request ID" which will be used to identify the response as well as the correct response pipe. The client must create this pipe itself, named with the following structure: ~/.var/app/net.retrodeck.retrodeck/config/retrodeck/api/response_{request_id}

After the API server has completed its response, it will remove this response pipe itself.

API Request Structure

Every API request consists of a single JSON object which contains all the needed information for the request. Required keys:

action - The desired action to be processed for the request. This splits the request into one of three classes: "get", "set" or "do".
request - The specific request to be processed
version - This is a key to identify what version of the RetroDECK API you are attempting to interact with. Currently the only valid option is "1.0", but this is a placeholder for possible future upgrades and backwards compatibility.
request_id - The unique (but arbitrary) request ID generated by the client. Optional keys:
data - This is an object containing additional information regarding the action to be taken. This can be a single key/value pair, or a series of nested objects each with their own information.

Example: compressible_games

Here is an example of a full request for the RetroDECK API. The request is for a list of all games that can be identified as being compressible into the zip format via compressible_games.

In this example structure, these keys have the following meaning:

status - Will return either "success" or "error", depending on the outcome of the request.
result - Will be a single or array of objects containing the response information.
message - Only for error responses, will contain some information about the nature of the error.
request_id - The request ID of the request that prompted this response.

If using named pipes for communication, after a response is processed the API server will remove the response pipe, indicating that the API transaction is complete.

Example Request: compressible_games

{
  "action": "get",
  "request": "compressible_games",
  "data": {
    "format": "zip"
  },
  "version": "1.0",
  "request_id": "12345"
}

Success Response: compressible_games

After receiving a proper request, the RetroDECK API will respond with this structure for a successful response:

{
  "status": "<status_report>",
  "result": {
   <response contents>
  },
  "request_id": "<request_id>"
}

Failure Response: compressible_games

In the case of an error:

{
  "status": "error",
  "message": "<error message>",
  "request_id": "<request_id>"
}

Full Response: compressible_games

Here is an example of a full response for the RetroDECK API, responding to the previous example request for zip-compressible games data.

{
  "status": "success",
  "result": [
    {
      "game": "/home/deck/retrodeck/roms/snes/3 Ninjas Kick Back (USA).sfc",
      "compression": "zip"
    },
    {
      "game": "/home/deck/retrodeck/roms/snes/Aero Fighters (USA).sfc",
      "compression": "zip"
    }
  ],
  "request_id": "client_1746640357_8454"
}

In this example, the "result" information is an array of objects, each with their own key/value pairs. The result data will vary depending on request, but will always reside within the "result" key.

Here is another example request, for the value of a setting named rdhome in the paths section of the retrodeck.cfg file, using the config file format retrodeck:

{
  "action": "get",
  "request":"setting_value",
  "data": {
    "setting_file": "/var/config/retrodeck/retrodeck.cfg",
    "setting_name": "rdhome",
    "system_name": "retrodeck",
    "section_name": "paths"
    },
  "version": "1.0",
  "request_id": "54321"
}

and the response for that request:

{
  "status": "success",
  "result": {
    "setting_name": "rdhome",
    "setting_value": "/home/deck/retrodeck"
  },
  "request_id": "54321"
}