API

Saltcorn exposes a REST-like JSON API that allows that allows reading and writing to the tables subject to authentication and authorisation.

Authorisation

Before you can use the API, you need to ensure that the user as which you intend to authenticate has read (and write, if necessary) permission to the table you would like to access. Go to the table settings for that table, and at the bottom of the screen, there is a form that allows you to set the minimal role for reading and writing. The user who is to access the table through the API must have a role that is greater or equal to this set role.

Authentication

If the table has read or write access for public users, you can use the API as documented below with no further authentication.

To authenticate as a specific user to access a table which has read or write access for non-public users only, you need to obtain an API token. As the administrator, go to the Users option under the Settings menu (not user settings under the user menu, which is the settings for your personal account only), and click on one of the users. At the bottom of the page, there is a card titled API token. If no API token is listed, click the "generate" button to generate the API token.

A user can have at most one API token. Clicking reset when there is an existing API token will invalidate the previous API token which will no longer be usable.

The API token can be used in one of these ways:

• set it as a Bearer in the Authorisation HTTP request header
• set it as the access_token in the query string
• in a POST body, set it as the access_token key in the JSON object.

Reading

To read from the API, make a GET request to /api/{table_name}. This will return an array of rows as JSON objects, wrapped in a JSON object with the key success. For example:

GET /api/persons 
->
{success: [{id: 1, name: "Fred"},...]}

You can restrict the rows returned by adding qualifications to the query string. For instance, to return the row with id=5, make a GET request to /api/{table_name}?id=5

Creating

To create a new row, make a POST request to /api/{table_name}. The body of the POST request should contain a JSON object specifying the values in each field. Non-required fields can be omitted.

The request will return the id of the created newly created row.

Updating

To change a value in an existing row, make a POST request to /api/{table_name}/{id}. The body of the POST request should contain a JSON object specifying the values in each field which is to change. Any fields omitted will be unchanged. Required fields may be omitted if they are not to change

Deleting

To delete an existing row, make a DELETE request to /api/{table_name}/{id}. The request will return either with a JSON object { success: true } if the deletion were successful, or a JSON object {error: error_message_string} if the deletion was not successful (the likely cause of which is that another table holds a key reference to this row)

Alternative API access

For a more powerful API, we recommend running Hasura (for a GraphQL API) or PostgREST (for a REST API) in parallel with Saltcorn against the PostgreSQL database used by the Saltcorn instance.