RPC API¶

Mathesar has an API available at /api/rpc/v0/ which follows the JSON-RPC spec version 2.0.

About¶

Status¶

We are currently in the process of transitioning our API architecture from a RESTful API to this RPC-style API, and we hope to have all functionality available through the RPC API by Mathesar’s beta release.

Stability

The RPC API is not yet stable and may change in the future, even after we’ve completed the transition to the RPC API architecture. If you build logic that depends on this API, be mindful that it may change in the future without warning or notice.

Usage¶

To use an RPC function:

Call it with a dot path starting from its root path.
Always use named parameters.
Ensure that your request includes HTTP headers for valid session IDs, as well as CSRF cookies and tokens.

Example

To call function add_from_known_connection from the connections section of this page, you’d send something like:

POST /api/rpc/v0/

{
  "jsonrpc": "2.0",
  "id": 234,
  "method": "connections.add_from_known_connection",
  "params": {
    "nickname": "anewconnection",
    "db_name": "mynewcooldb"
  },
}

connections ¶

Classes and functions exposed to the RPC endpoint for creating connections.

add_from_known_connection ¶

add_from_known_connection(
    *,
    nickname,
    database,
    create_db=False,
    connection_id=None,
    sample_data=[]
)

Add a new connection from an already existing one.

If no connection_id is passed, the internal database connection will be used.

Parameters:

Name	Type	Description	Default
`nickname`	`str`	Identify the added connection. Should be unique.	required
`database`	`str`	The name of the database on the server.	required
`create_db`	`bool`	Whether we should create the database `database` if it doesn’t already exist.	`False`
`connection_id`	`int`	Identifies the known connection when combined with the user_database value for the connection_type parameter	`None`
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

Returns:

Type	Description
`DBModelReturn`	Metadata about the Database associated with the connection.

add_from_scratch ¶

add_from_scratch(
    *,
    nickname,
    database,
    user,
    password,
    host,
    port,
    sample_data=[]
)

Add a new connection to a PostgreSQL server from scratch.

This requires inputting valid credentials for the connection. When setting up the connection, therefore, the database must already exist on the PostgreSQL server.

Parameters:

Name	Type	Description	Default
`nickname`	`str`	Identify the added connection. Should be unique.	required
`database`	`str`	The name of the database on the server.	required
`user`	`str`	A valid user (role) on the server, with `CONNECT` and `CREATE` privileges on the database given by `database`.	required
`password`	`str`	The password for `user`.	required
`host`	`str`	The hostname or IP address of the PostgreSQL server.	required
`port`	`int`	The port of the PostgreSQL server.	required
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

Returns:

Type	Description
`DBModelReturn`	Metadata about the Database associated with the connection.

DBModelReturn ¶

Bases: TypedDict

Information about a database model.

Attributes:

Name	Type	Description
`id`	`int`	The Django id of the Database object added.
`nickname`	`str`	Used to identify the added connection.
`database`	`str`	The name of the database on the server.
`username`	`str`	The username of the role for the connection.
`host`	`str`	The hostname or IP address of the Postgres server.
`port`	`int`	The port of the Postgres server.

Responses¶

Success¶

Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form:

{
  "jsonrpc": "2.0",
  "id": 234,
  "result": <any>
}

The result is whatever was returned by the underlying function.

Errors¶

When an error is produced by a call to the RPC endpoint, we produce an error of the following form:

{
  "jsonrpc": "2.0",
  "id": 234,
  "error": {
    "code": <int>,
    "message": <str>
  }
}

The code is a negative integer. Some codes are produced according to the JSON-RPC spec.

Other error codes are grouped according to the library that produced the Exception:

builtins: -31xxx
psycopg or psycopg2: -30xxx
django: -29xxx
mathesar (our code): -28xxx
db (our code): -27xxx
sqlalchemy: -26xxx
other: -25xxx

Unrecognized errors from a given library return a “round number” code, so an unknown builtins error gets the code -31000.