# API Reference # Overview The **XINA API** (or **XAPI**) provides programmatic access to a XINA server. > Note that client applications do not connect directly to the server. The [XINA Tunnel](/books/utilities/page/xina-tunnel) utility performs the actual server connection, authentication, and security, and provides a local server for local client to connect. XAPI is built on the **XINA Protocol** (or **XProtocol**), a TCP format used to communicate with the XINA server. It is designed to be simple and easy to implement across many languages and environments, using standard UTF-8 character encoding and JSON data structures. ## Tokens XProtocol is intended to be parsed in-place as a stream is read. This is achieved with variable length **tokens** of the following format: - prefix length: one byte UTF-8 digit indicating length of the prefix in bytes - prefix: UTF-8 digit(s) indicating the length of the content in bytes - content: UTF-8 encoded string or binary data of (prefix count) bytes For example: - `14cake` = `"cake"` - `213big hamburger` = `"big hamburger"` The maximum allowed length of a single token is 2GB. A token may also be empty, which can be denoted with either the prefix `10` or the shorthand prefix `0`. > Note that the content length is specified in *bytes*, not *characters*. Because UTF-8 is a variable length encoding format, it is recommend to first convert string data to bytes before creating a token for an accurate count. ## Packets Tokens are combined together into **packets**, which form all communication between the client and server. ### Client Packets **Client packets** are sent from the client to server. They use the following format: - packet type :: one byte UTF-8 character - header token :: JSON object containing header information (used primarily for system purposes, typically empty) - content token :: UTF-8 encoded JSON object, binary data, or empty depending on token type Client packets use the following packet types:
Type | Code | Description |
---|---|---|
`ACTION` | `A` | contains an API action (most common packet type) |
`BINARY` | `B` | contains binary data (used for transmitting file data) |
`CLOSE` | `X` | closes the connection |
`CONTINUE` | `C` | prompts continuing a data stream from the server |
`END` | `E` | indicates the end of a series of binary packets |
`INIT` | `I` | initializes the connection |
`KEEPALIVE` | `K` | ignored by both server and client, keeps connection open |
`OBJECT` | `O` | indicates the start of a binary object |
Type | Code | Description |
---|---|---|
`KEEPALIVE` | `K` | ignored by both server and client, keeps connection open |
`SERVER` | `S` | primary server packet type, used for all functions |
Code | Description |
---|---|
`1XX` | Success, more data available |
`2XX` | Success, data ended |
`4XX` | Content error |
`5XX` | Server error |
client | server | |
---|---|---|
`ACTION` | `->` | |
`<-` | `SERVER` |
client | server | |
---|---|---|
`ACTION` | `->` | |
`<-` | `SERVER` `1XX` | |
`CONTINUE` | `->` | |
`<-` | `SERVER` `1XX` | |
`CONTINUE` | `->` | |
`<-` | `SERVER` `2XX` |
client | server | notes | |
---|---|---|---|
`OBJECT` | `->` | initializes the object | |
`BINARY` | `->` | contains binary data | |
`...` | `->` | contains additional binary data as needed | |
`END` | `->` | ends the object | |
`<-` | `SERVER` `2XX` | content contains `object_id` |