Exciton Boost Reference - Remote Procedure Calls
This page describes the Exciton Boost RPC API which works alongside the Exciton Boost REST API to provide higher value server side functionality with remote procedure calls based on the JSON-RPC syntax. Each resource has a matching RPC endpoint which provides a batchable "script" of methods to manipulate the resource. All RPC calls use the POST method, and JSON is used in all requests, and in responses which include a body.
For the most part, the Exciton Boost RPC API follows the JSON-RPC 2.0 specifications, and should conform to any software that supports that specification, but there are assumptions the Exciton Boost RPC API makes that are more specialized.
- Batched methods are executed sequentially, never in parallel.
- Failure in one method will cause the failure of each subsequent method in a batch.
- RPC calls against Document and RTItem resources will automatically update the note to disk only upon successful completion of all method(s) where at least one method may change content.
- Successful requests with content will return a statuss of 200, while successful requests with no content will return a status of 204.
- Failure to parse the JSON in a request will return a status of 500, along with a JSON-RPC error response.
- Failure in any method will return an error status appropiate to the first failure, such as 400 for a bad request, along with a JSON-RPC error response which may provide more detail.
Remote Procedure Calls are grouped together by a prefix on the method name such as "db.addDocsWithJSON", where the "db." indicates that it is a database level method. A single batch request on a document might well use a database method prefixed by "db." as well as document methods prefixed by "doc." and even rich text methods prefixed by "rti." or "rtc.".
Method groups by prefix:
- "db." - Database methods act on the specific database. Available on all endpoints.
- "doc." - Document methods act on a specified document. Available on both specified documents and when each document in a collection is acted on.
- "rti." - Methods acting on the named rich text item, or when a script acts on each named rich text item. For the purposes of Exciton Boost, both in the REST and RPC versions, Body is treated as a single RTItem even if it consists of several items on the document.
- "rtc." - Methods acting on a defined chunk of the rich text item, such as "Table 1; Row 3; Column 2". Until a chunk is defined, "Everything" is assumed, meaning the chunk is the entire rich text item.
- "coll." - Methods acting on a collection of documents based on a view or folder or other selection, often modified by query parameters.
JSON-RPC methods
Methods are expressed as a single JSON object or an array of JSON objects. The "jsonrpc" element is required and must have a value of exactly "2.0". The "method" element is required, and must
be prefixed by one of the method groups followed by a period followed by the method name. (e.g., "rtc.appendText"). The "params" element is only required if the method
has required parameters. The "id" parameter is only allowed when there is a valid return value to the method, and may be skipped if no response is required.
Database RPC endpoint
POST {dbpath}/api/boost/rpc
The Database RPC endpoint provides methods which act on the specified database as a whole.
Request Body
{
"jsonrpc": "2.0",
"method": db.methodName,
"params": [param1, param2, ...],
"id": num_or_string_id
}
Sample request
In the example below, a method is called to get the database title. It has no params, but it does have an "id", as a return is expected.
{
"jsonrpc": "2.0",
"method": "db.getTitle",
"id": 1
}
Sample response
{
200 OKMethod successful. Result below. Would use204if no return values.
"jsonrpc": "2.0",
"result": "Marketing Quotas",
"id": 1
}
As there was only one method, the result is an object rather than an array of objects.
Document RPC endpoint
POST {dbpath}/api/boost/documents/{unid}/rpc
The Document RPC endpoint provides methods which act on the specified document identified with the document unique id (unid).
Request Body
{
"jsonrpc": "2.0",
"method": doc.methodName,
"params": [param1, param2, ...],
"id": num_or_string_id
}
Sample batch request
In the example below, two methods are called sequentially. The first method, connectRTItem, is called at the document scope and creates a connection to the rich text Body item. The second, getIsConnected, gets the
IsConnected value. It has no params, but it does have an "id"
[
{
"jsonrpc": "2.0",
"method": "rti.connectRTItem",
"params": ["Body", true]
},
{
"jsonrpc": "2.0",
"method": "rti.getIsConnected",
"id": "flag"
}
]
Sample response
[
200 OKAll methods successful. Result below. Would use204 No Contentif no return values.
{
"jsonrpc": "2.0",
"result": true,
"id": "flag"
}
]
As there was an array of methods, the result is an array, even though there is only a single result object.
Rich Text RPC endpoint
POST {dbpath}/api/boost/documents/{unid}/rtiems/{name}/rpc
The Rich Text RPC endpoint provides methods which act on the rich text item as a whole (prefix rti.) as well as a defined chunk within the rich text (prefix rtc.).
Request Body
{
"jsonrpc": "2.0",
"method": rti.methodName,
"params": [param1, param2, ...],
"id": num_or_string_id
}{
"jsonrpc": "2.0",
"method": rtc.methodName,
"params": [param1, param2, ...],
"id": num_or_string_id
}
Sample batch request
In the example below, the first method, connectRTItem, is called at the document scope and defines the chunk to be used, and the following methods operate on that chunkof rich text. None of the methods has a return value, so no "id" is used.
[
{
"jsonrpc": "2.0",
"method": "doc.defineRTChunk",
"params": ["Table 1; Row 2; Column 2"]
},
{
"jsonrpc": "2.0",
"method": "rtc.appendNewLines",
"params": [1, false]
},
{
"jsonrpc": "2.0",
"method": "rtc.appendText",
"params": ["Past Due", "+Italic +Bold #ff0000"]
}
]
Sample response
204 No Content All methods successful, but no return value needed.