Skip to content

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.