Free cookie consent management tool by TermsFeed Policy Generator

Remote Procedure Call (RPC)

Installed API version : 1.1.5

Protocol reference:

Below you will find a detailed description of all the RPC protocols installed in this environment. This includes supported content types as well as target URLs for anonymous and authenticated access. Use this information to interact with this environment from a remote location.

Libraries for remote procedure calls and parsing exists for most major languages and platforms - use a tested, standard library for consistent results.

JSON-RPC

For JSON-RPC protocol, use any one of:

Example POST request using curl with Content-Type header and body: 

user: ~ > cat body.json
{"params": ["WikiStart"], "method": "wiki.getPage", "id": 123}
user: ~ > curl -H "Content-Type: application/json" --data @body.json https://dev.heuristiclab.com/trac.fcgi/rpc
{"id": 123, "error": null, "result": "= Welcome to....

Implementation details:

  • JSON-RPC has no formalized type system, so a class-hint system is used for input and output of non-standard types:
    • {"__jsonclass__": ["datetime", "YYYY-MM-DDTHH:MM:SS"]} => DateTime (UTC)
    • {"__jsonclass__": ["binary", "<base64-encoded>"]} => Binary
  • "id" is optional, and any marker value received with a request is returned with the response.

XML-RPC

For XML-RPC protocol, use any one of:

There should be XML-RPC client implementations available for all popular programming languages. Example call using curl: 

user: ~ > cat body.xml
<?xml version="1.0"?>
<methodCall>
<methodName>wiki.getPage</methodName>
<params>
<param><string>WikiStart</string></param>
</params>
</methodCall>
user: ~ > curl -H "Content-Type: application/xml" --data @body.xml https://dev.heuristiclab.com/trac.fcgi/rpc
<?xml version='1.0'?>
<methodResponse>
<params>
<param>
<value><string>= Welcome to....

The following snippet illustrates how to perform authenticated calls in Python. 

>>> from xmlrpclib import ServerProxy
>>> p = ServerProxy('https://anonymous:your_password@dev.heuristiclab.com/trac.fcgi/login/rpc')
>>> p.system.getAPIVersion()
[1, 1, 5]

RPC exported functions

search - Search Trac.

Function Description Permission required
array search.getSearchFilters() Retrieve a list of search filters with each element in the form (name, description). SEARCH_VIEW
array search.performSearch(string query, array filters=None) Perform a search using the given filters. Defaults to all if not provided. Results are returned as a list of tuples in the form (href, title, date, author, excerpt). SEARCH_VIEW

system - Core of the RPC system.

Function Description Permission required
array system.multicall(array signatures) Takes an array of RPC calls encoded as structs of the form (in a Pythonish notation here): {'methodName': string, 'params': array}. For JSON-RPC multicall, signatures is an array of regular method call structs, and result is an array of return structures. XML_RPC
array system.listMethods() This method returns a list of strings, one for each (non-system) method supported by the RPC server. XML_RPC
string system.methodHelp(string method) This method takes one parameter, the name of a method implemented by the RPC server. It returns a documentation string describing the use of that method. If no such string is available, an empty string is returned. The documentation string may contain HTML markup. XML_RPC
array system.methodSignature(string method) This method takes one parameter, the name of a method implemented by the RPC server. It returns an array of possible signatures for this method. A signature is an array of types. The first of these types is the return type of the method, the rest are parameters. XML_RPC
array system.getAPIVersion() Returns a list with three elements. First element is the epoch (0=Trac 0.10, 1=Trac 0.11 or higher). Second element is the major version number, third is the minor. Changes to the major version indicate API breaking changes, while minor version changes are simple additions, bug fixes, etc. XML_RPC

ticket - An interface to Trac's ticketing system.

Function Description Permission required
array ticket.query(string qstr="status!=closed") Perform a ticket query, returning a list of ticket ID's. All queries will use stored settings for maximum number of results per page and paging options. Use max=n to define number of results to receive, and use page=n to page through larger result sets. Using max=0 will turn off paging and return all results. By resource
array ticket.getRecentChanges(DateTime since) Returns a list of IDs of tickets that have changed since timestamp. By resource
array ticket.getAvailableActions(int id) Deprecated - will be removed. Replaced by getActions(). By resource
array ticket.getActions(int id) Returns the actions that can be performed on the ticket as a list of [action, label, hints, [input_fields]] elements, where input_fields is a list of [name, value, [options]] for any required action inputs. By resource
array ticket.get(int id) Fetch a ticket. Returns [id, time_created, time_changed, attributes]. By resource
int ticket.create(string summary, string description, struct attributes={}, boolean notify=False, DateTime when=None) Create a new ticket, returning the ticket ID. Overriding 'when' requires admin permission. TICKET_CREATE
array ticket.update(int id, string comment, struct attributes={}, boolean notify=False, string author="", DateTime when=None) Update a ticket, returning the new ticket in the same form as get(). 'New-style' call requires two additional items in attributes: (1) 'action' for workflow support (including any supporting fields as retrieved by getActions()), (2) '_ts' changetime token for detecting update collisions (as received from get() or update() calls). Calling update without 'action' and '_ts' changetime token is deprecated, and will raise errors in a future version. By resource
int ticket.delete(int id) Delete ticket with the given id. By resource
struct ticket.changeLog(int id, int when=0) Return the changelog as a list of tuples of the form (time, author, field, oldvalue, newvalue, permanent). While the other tuple elements are quite self-explanatory, the permanent flag is used to distinguish collateral changes that are not yet immutable (like attachments, currently). :since 1.0: the db parameter is no longer needed and will be removed in version 1.1.1 By resource
array ticket.listAttachments(int ticket) Lists attachments for a given ticket. Returns (filename, description, size, time, author) for each attachment. By resource
Binary ticket.getAttachment(int ticket, string filename) returns the content of an attachment. By resource
string ticket.putAttachment(int ticket, string filename, string description, Binary data, boolean replace=True) Add an attachment, optionally (and defaulting to) overwriting an existing one. Returns filename. By resource
boolean ticket.deleteAttachment(int ticket, string filename) Delete an attachment. By resource
array ticket.getTicketFields() Return a list of all ticket fields fields. TICKET_VIEW

ticket.component - Interface to ticket component objects.

Function Description Permission required
array ticket.component.getAll() Get a list of all ticket component names. TICKET_VIEW
struct ticket.component.get(string name) Get a ticket component. TICKET_VIEW
int ticket.component.delete(string name) Delete a ticket component TICKET_ADMIN
int ticket.component.create(string name, struct attributes) Create a new ticket component with the given attributes. TICKET_ADMIN
int ticket.component.update(string name, struct attributes) Update ticket component with the given attributes. TICKET_ADMIN

ticket.milestone - Interface to ticket milestone objects.

Function Description Permission required
array ticket.milestone.getAll() Get a list of all ticket milestone names. TICKET_VIEW
struct ticket.milestone.get(string name) Get a ticket milestone. TICKET_VIEW
int ticket.milestone.delete(string name) Delete a ticket milestone TICKET_ADMIN
int ticket.milestone.create(string name, struct attributes) Create a new ticket milestone with the given attributes. TICKET_ADMIN
int ticket.milestone.update(string name, struct attributes) Update ticket milestone with the given attributes. TICKET_ADMIN

ticket.priority - Interface to ticket priority.

Function Description Permission required
array ticket.priority.getAll() Get a list of all ticket priority names. TICKET_VIEW
string ticket.priority.get(string name) Get a ticket priority. TICKET_VIEW
int ticket.priority.delete(string name) Delete a ticket priority TICKET_ADMIN
int ticket.priority.create(string name, string value) Create a new ticket priority with the given value. TICKET_ADMIN
int ticket.priority.update(string name, string value) Update ticket priority with the given value. TICKET_ADMIN

ticket.resolution - Interface to ticket resolution.

Function Description Permission required
array ticket.resolution.getAll() Get a list of all ticket resolution names. TICKET_VIEW
string ticket.resolution.get(string name) Get a ticket resolution. TICKET_VIEW
int ticket.resolution.delete(string name) Delete a ticket resolution TICKET_ADMIN
int ticket.resolution.create(string name, string value) Create a new ticket resolution with the given value. TICKET_ADMIN
int ticket.resolution.update(string name, string value) Update ticket resolution with the given value. TICKET_ADMIN

ticket.severity - Interface to ticket severity.

Function Description Permission required
array ticket.severity.getAll() Get a list of all ticket severity names. TICKET_VIEW
string ticket.severity.get(string name) Get a ticket severity. TICKET_VIEW
int ticket.severity.delete(string name) Delete a ticket severity TICKET_ADMIN
int ticket.severity.create(string name, string value) Create a new ticket severity with the given value. TICKET_ADMIN
int ticket.severity.update(string name, string value) Update ticket severity with the given value. TICKET_ADMIN

ticket.status - An interface to Trac ticket status objects. Note: Status is defined by workflow, and all methods except getAll() are deprecated no-op methods - these will be removed later.

Function Description Permission required
array ticket.status.getAll() Returns all ticket states described by active workflow. TICKET_VIEW
struct ticket.status.get(string name) Deprecated no-op method. Do not use. TICKET_VIEW
int ticket.status.delete(string name) Deprecated no-op method. Do not use. TICKET_ADMIN
int ticket.status.create(string name, struct attributes) Deprecated no-op method. Do not use. TICKET_ADMIN
int ticket.status.update(string name, struct attributes) Deprecated no-op method. Do not use. TICKET_ADMIN

ticket.type - Interface to ticket type.

Function Description Permission required
array ticket.type.getAll() Get a list of all ticket type names. TICKET_VIEW
string ticket.type.get(string name) Get a ticket type. TICKET_VIEW
int ticket.type.delete(string name) Delete a ticket type TICKET_ADMIN
int ticket.type.create(string name, string value) Create a new ticket type with the given value. TICKET_ADMIN
int ticket.type.update(string name, string value) Update ticket type with the given value. TICKET_ADMIN

ticket.version - Interface to ticket version objects.

Function Description Permission required
array ticket.version.getAll() Get a list of all ticket version names. TICKET_VIEW
struct ticket.version.get(string name) Get a ticket version. TICKET_VIEW
int ticket.version.delete(string name) Delete a ticket version TICKET_ADMIN
int ticket.version.create(string name, struct attributes) Create a new ticket version with the given attributes. TICKET_ADMIN
int ticket.version.update(string name, struct attributes) Update ticket version with the given attributes. TICKET_ADMIN

wiki - Superset of the ​WikiRPC API.

Function Description Permission required
struct wiki.getRecentChanges(DateTime since) Get list of changed pages since timestamp By resource
int wiki.getRPCVersionSupported() Returns 2 with this version of the Trac API. WIKI_VIEW
string wiki.getPage(string pagename, int version=None) Get the raw Wiki text of page, latest version. By resource
string wiki.getPageVersion(string pagename, int version=None) Get the raw Wiki text of page, latest version. By resource
string wiki.getPageHTML(string pagename, int version=None) Return latest version of page as rendered HTML, utf8 encoded. By resource
string wiki.getPageHTMLVersion(string pagename, int version=None) Return latest version of page as rendered HTML, utf8 encoded. By resource
array wiki.getAllPages() Returns a list of all pages. The result is an array of utf8 pagenames. By resource
struct wiki.getPageInfo(string pagename, int version=None) Returns information about the given page. By resource
struct wiki.getPageInfoVersion(string pagename, int version=None) Returns information about the given page. By resource
boolean wiki.putPage(string pagename, string content, struct attributes) writes the content of the page. By resource
array wiki.listAttachments(string pagename) Lists attachments on a given page. By resource
Binary wiki.getAttachment(string path) returns the content of an attachment. By resource
boolean wiki.putAttachment(string path, Binary data) (over)writes an attachment. Returns True if successful. This method is compatible with WikiRPC. putAttachmentEx has a more extensive set of (Trac-specific) features. By resource
boolean wiki.putAttachmentEx(string pagename, string filename, string description, Binary data, boolean replace=True) Attach a file to a Wiki page. Returns the (possibly transformed) filename of the attachment. Use this method if you don't care about WikiRPC compatibility. By resource
boolean wiki.deletePage(string name, int version=None) Delete a Wiki page (all versions) or a specific version by including an optional version number. Attachments will also be deleted if page no longer exists. Returns True for success. By resource
boolean wiki.deleteAttachment(string path) Delete an attachment. By resource
array wiki.listLinks(string pagename) Not implemented WIKI_VIEW
string wiki.wikiToHtml(string text) Render arbitrary Wiki text as HTML. WIKI_VIEW