API Reference

API Reference

This reference mirrors the public API in PawnREST.inc.

Constants

HTTP Methods

HTTP_METHOD_GET, HTTP_METHOD_POST, HTTP_METHOD_PUT, HTTP_METHOD_PATCH, HTTP_METHOD_DELETE, HTTP_METHOD_HEAD, HTTP_METHOD_OPTIONS

Conflict Modes (Inbound Upload Route)

CONFLICT_RENAME, CONFLICT_OVERWRITE, CONFLICT_REJECT

Corrupt File Actions

CORRUPT_DELETE, CORRUPT_QUARANTINE, CORRUPT_KEEP

Upload Modes

UPLOAD_MODE_MULTIPART, UPLOAD_MODE_RAW

Status Constants

• Upload status: UPLOAD_PENDING, UPLOAD_UPLOADING, UPLOAD_COMPLETED, UPLOAD_FAILED, UPLOAD_CANCELLED
• Outbound request status: REQUEST_PENDING, REQUEST_REQUESTING, REQUEST_COMPLETED, REQUEST_FAILED, REQUEST_CANCELLED

Error Codes (PAWNREST_ERR_*)

PAWNREST_ERR_NONE, PAWNREST_ERR_INVALID_URL, PAWNREST_ERR_UNSUPPORTED_SCHEME, PAWNREST_ERR_TLS_UNAVAILABLE, PAWNREST_ERR_TLS_INVALID_CERTS, PAWNREST_ERR_FILE_NOT_FOUND, PAWNREST_ERR_EMPTY_FILE, PAWNREST_ERR_CANCELLED, PAWNREST_ERR_HTTP_STATUS, PAWNREST_ERR_NETWORK, PAWNREST_ERR_TIMEOUT, PAWNREST_ERR_TLS_HANDSHAKE, PAWNREST_ERR_UNKNOWN, PAWNREST_ERR_JSON_PARSE, PAWNREST_ERR_WEBSOCKET

JSON Node Types

PAWNREST_NODE_NUMBER, PAWNREST_NODE_BOOLEAN, PAWNREST_NODE_STRING, PAWNREST_NODE_OBJECT, PAWNREST_NODE_ARRAY, PAWNREST_NODE_NULL
Aliases: JSON_NODE_*

Server Control

native bool:REST_Start(port);
native bool:REST_StartTLS(port, const certPath[], const keyPath[]);
native bool:REST_Stop();
native REST_IsRunning();
native REST_GetPort();
native REST_IsTLSEnabled();

Inbound Upload Routes

native FILE_RegisterRoute(const endpoint[], const path[], const allowedExts[], maxSizeMb);
native bool:FILE_AddAuthKey(routeId, const key[]);
native bool:FILE_RemoveAuthKey(routeId, const key[]);
native bool:FILE_SetConflict(routeId, mode);
native bool:FILE_SetCorruptAction(routeId, action);
native bool:FILE_SetRequireCRC32(routeId, bool:required);
native bool:FILE_RemoveRoute(routeId);

Custom REST API Routes

native REST_RegisterAPIRoute(method, const endpoint[], const callback[]);
native bool:REST_RemoveAPIRoute(routeId);
native bool:REST_SetRouteAuthKey(routeId, const key[]);

REST Request Data Access

native REST_GetRequestIP(requestId, output[], outputSize);
native REST_GetRequestMethod(requestId);
native REST_GetRequestPath(requestId, output[], outputSize);
native REST_GetRequestBody(requestId, output[], outputSize);
native REST_GetRequestBodyLength(requestId);
native REST_GetParam(requestId, const name[], output[], outputSize);
native REST_GetParamInt(requestId, const name[]);
native REST_GetQuery(requestId, const name[], output[], outputSize);
native REST_GetQueryInt(requestId, const name[], defaultValue = 0);
native REST_GetHeader(requestId, const name[], output[], outputSize);

Behavior notes:

1. REST_GetQuery* reads query values from the full request target (/path?key=value) and falls back to parsed params.
2. REST_GetHeader name matching is case-insensitive.

JSON Node API

Parse and Lifecycle

native JsonParse(const json[]);
native GetRequestJsonNode(requestId);
native JsonNodeType(nodeId);
native JsonStringify(nodeId, output[], outputSize);
native bool:JsonCleanup(nodeId);

Constructors

native JsonObject(...);
native JsonArray(...);
native JsonString(const value[]);
native JsonInt(value);
native JsonFloat(Float:value);
native JsonBool(bool:value);
native JsonNull();
native JsonAppend(leftNodeId, rightNodeId);

Object Operations

native bool:JsonSetObject(objectNodeId, const key[], valueNodeId);
native bool:JsonSetString(objectNodeId, const key[], const value[]);
native bool:JsonSetInt(objectNodeId, const key[], value);
native bool:JsonSetFloat(objectNodeId, const key[], Float:value);
native bool:JsonSetBool(objectNodeId, const key[], bool:value);
native bool:JsonSetNull(objectNodeId, const key[]);
native bool:JsonHas(objectNodeId, const key[]);
native JsonGetNode(objectNodeId, const key[]);
native JsonGetString(objectNodeId, const key[], output[], outputSize);
native JsonGetInt(objectNodeId, const key[], defaultValue = 0);
native Float:JsonGetFloat(objectNodeId, const key[], Float:defaultValue = 0.0);
native bool:JsonGetBool(objectNodeId, const key[], bool:defaultValue = false);

Array Operations

native JsonArrayLength(arrayNodeId);
native JsonArrayGetNode(arrayNodeId, index);
native bool:JsonArrayAppend(arrayNodeId, valueNodeId);
native bool:JsonArrayAppendString(arrayNodeId, const value[]);
native bool:JsonArrayAppendInt(arrayNodeId, value);
native bool:JsonArrayAppendFloat(arrayNodeId, Float:value);
native bool:JsonArrayAppendBool(arrayNodeId, bool:value);
native bool:JsonArrayAppendNull(arrayNodeId);

Response Helpers

native bool:Respond(requestId, status, const body[], const contentType[] = "application/json");
native bool:RespondJSON(requestId, status, const json[]);
native bool:RespondNode(requestId, status, nodeId);
native bool:RespondError(requestId, status, const message[]);
native bool:SetResponseHeader(requestId, const name[], const value[]);

File Route REST Permissions and File Ops

native bool:FILE_AllowList(routeId, bool:allow);
native bool:FILE_AllowDownload(routeId, bool:allow);
native bool:FILE_AllowDelete(routeId, bool:allow);
native bool:FILE_AllowInfo(routeId, bool:allow);

native FILE_GetCount(routeId);
native FILE_GetName(routeId, index, output[], outputSize);
native bool:FILE_Delete(routeId, const filename[]);
native FILE_GetSize(routeId, const filename[]);

File Route REST Endpoints

When enabled via FILE_Allow*, the following HTTP endpoints are available:

Endpoint	Permission	Description
GET {route}/files	FILE_AllowList	List all files
GET {route}/files/{name}	FILE_AllowDownload	Download file
GET {route}/files/{name}/info	FILE_AllowInfo	File metadata
DELETE {route}/files/{name}	FILE_AllowDelete	Delete file

Response Formats

GET {route}/files:

{ "success": true, "count": 3, "files": ["file1.map", "file2.json", "test.map"] }

GET {route}/files/{name}/info:

{ "success": true, "name": "file1.map", "size": 12345, "modified": 1712419200 }

DELETE {route}/files/{name}:

{ "success": true, "deleted": "file1.map" }

GET {route}/files/{name}: Returns raw file content.

Outgoing Upload API

native FILE_Upload(
    const url[],
    const filepath[],
    const filename[] = "",
    const authKey[] = "",
    const customHeaders[] = "",
    calculateCrc32 = 1,
    mode = UPLOAD_MODE_MULTIPART,
    bool:verifyTls = true
);

native FILE_CreateUploadClient(const baseUrl[], const defaultHeaders[] = "", bool:verifyTls = true);
native bool:FILE_RemoveUploadClient(clientId);
native bool:FILE_SetUploadClientHeader(clientId, const name[], const value[]);
native bool:FILE_RemoveUploadClientHeader(clientId, const name[]);

native FILE_UploadWithClient(
    clientId,
    const path[],
    const filepath[],
    const filename[] = "",
    const authKey[] = "",
    const customHeaders[] = "",
    calculateCrc32 = 1,
    mode = UPLOAD_MODE_MULTIPART
);

native bool:FILE_CancelUpload(uploadId);
native FILE_GetUploadStatus(uploadId);
native FILE_GetUploadProgress(uploadId);
native FILE_GetUploadResponse(uploadId, output[], outputSize);
native FILE_GetUploadErrorCode(uploadId);
native FILE_GetUploadErrorType(uploadId, output[], outputSize);
native FILE_GetUploadHttpStatus(uploadId);

Outbound HTTP Request API

native REST_CreateRequestClient(const baseUrl[], const defaultHeaders[] = "", bool:verifyTls = true);
native bool:REST_RemoveRequestsClient(clientId);
native bool:REST_SetRequestsClientHeader(clientId, const name[], const value[]);
native bool:REST_RemoveRequestsClientHeader(clientId, const name[]);

native REST_Request(
    clientId,
    const path[],
    method,
    const callback[],
    const body[] = "",
    const headers[] = ""
);

native REST_RequestJSON(
    clientId,
    const path[],
    method,
    const callback[],
    jsonNodeId = -1,
    const headers[] = ""
);

native bool:REST_CancelRequest(requestId);
native REST_GetRequestStatus(requestId);
native REST_GetRequestHttpStatus(requestId);
native REST_GetRequestErrorCode(requestId);
native REST_GetRequestErrorType(requestId, output[], outputSize);
native REST_GetRequestResponse(requestId, output[], outputSize);

WebSocket Client API

native REST_WebSocketClient(const address[], const callback[], const headers[] = "", bool:verifyTls = true);
native REST_JsonWebSocketClient(const address[], const callback[], const headers[] = "", bool:verifyTls = true);
native bool:REST_WebSocketSend(socketId, const data[]);
native bool:REST_JsonWebSocketSend(socketId, nodeId);
native bool:REST_WebSocketClose(socketId, status = 1000, const reason[] = "");
native bool:REST_RemoveWebSocketClient(socketId);
native bool:REST_IsWebSocketOpen(socketId);

CRC32 Utilities

native FILE_VerifyCRC32(const filepath[], const expectedCrc[]);
native FILE_GetCRC32(const filepath[], output[], outputSize);
native FILE_Compare(const path1[], const path2[]);

Header Helper Stocks

stock bool:REST_RequestHeaders(output[], outputSize, const key[], const value[]);
stock bool:REST_RequestHeadersAppend(headers[], outputSize, const key[], const value[]);

Built-in Endpoints

• GET /health
• GET /stats

Callback Signatures

See Callbacks for full callback signatures and behavior.