RICREST is one of the two main transport protocols supported by RIC; the other is ROSSerial. Both can be wrapped by the RICSerial and RICFrame protocols.

RICREST is a form of HTTP REST protocol. It has some limitations, depending on the interface, to suit the channel carrying it. See **Interface support** below.

The RICREST payload is often plain text, but it can also carry binary data, such as HTTP body or file-upload information.

===== Interface support =====

The REST API supports the following interfaces:

  * **WiFi + HTTP:** the classic REST protocol.
    * REST GET with a string request and response.
    * REST POST using media encoding types including binary and JSON.
    * HTTP file transfer in both directions.
  * **SerialConsole:**
    * Minimal GET support using only the URL part of a GET request, with a string response returned to the console.
  * **BLE and TCP socket over RICSerial:**
    * GET with a string request and response.
    * POST with binary and JSON payloads.
    * File transfer.

===== RESTElementCode =====

The first byte of a RICREST packet is the **RESTElementCode**, which determines the format of the rest of the message.

For a standard REST API command, the RESTElementCode is **0x00**. The remaining message is a null-terminated string containing the REST command. The `http://…/api` prefix is removed before the command is sent over RICREST.

^ RESTElementCode (byte 0) ^ Meaning ^ Remainder of message ^
| 0x00 | URL | Null-terminated string containing the URL element of a REST API call. |
| 0x01 | CmdRespJSON | Null-terminated string used for responses. See **CmdRespJSON properties** below. |
| 0x02 | Body | `uint32_t index` \\ `uint32_t total` \\ `uint8[] binary data` — length determined by the overall message length. |
| 0x03 | CommandFrame | Null-terminated string containing a JSON object with these properties: `cmdName` (mandatory), `fileName`, `fileType`, `fileLen`, `fileCRC`, `reqStr`, `batchAck`. See **CommandFrame properties** below. |
| 0x04 | FileOrStreamBlock | `uint8_t streamID` (0 = ANY; 1..255 = numbered stream) \\ `uint24_t file position in bytes` \\ `uint8[] binary data` — length determined by the overall message length. |

===== CmdRespJSON properties =====

^ Property name ^ Values / description ^
| `rslt` | Result of the operation: `ok` or `fail`. |
| `req` | Original REST command from the request. |
| `error` | If present, the error string for the command. |
| `okto` | In file transfers, the `filePos` successfully reached in the received messages. |
| `sokto` | For sockets, the `streamPos` successfully received and accepted into the stream. |

===== CommandFrame properties =====

The CommandFrame uses JSON format.

^ Property name ^ Valid for cmdName ^ Values / description ^
| `cmdName` | All | Defines the sub-command: \\ `ufStart` — file upload start \\ `ufEnd` — file upload end \\ `ufCancel` — file upload cancel \\ `ufStatus` — status information |
| `fileName` | ufStart, ufEnd, ufCancel | Name of the file being uploaded. |
| `fileType` | ufStart, ufEnd | Type of file: `general` or `ricfirmware`. |
| `fileLen` | ufStart, ufEnd | Length of the file. |
| `blockCount` | ufEnd | Number of blocks sent. |
| `reqStr` | ufStart, ufEnd, ufCancel | REST API endpoint being used, generally `fileupload` or `espfwupdate`. |
| `batchAck` | ufStart | Number of FileBlock messages that can be sent in a batch before an acknowledgement is required. |
| `reason` | ufCancel, ufStatus | `userCancel` — user or controller cancelled \\ `notStarted` — file upload has not started \\ `OTAStartFailed` — robot failed to start the OTA process \\ `OTAStartedOK` — robot started the OTA process \\ `failRetries` — robot failed to acknowledge a block after retries \\ `failTimeout` — robot reached the overall file-upload timeout |