Skip to content

Tables and Access Groups ​

Every record lives in a table, in one access group. There is no schema to set up: a table is created by its first record and goes away when its last record is deleted.

A table is always written as a JSON object with its name and its access group:

kotlin
jsonOf("name" to "posts", "access_group" to "public")
java
SkapiJson.obj("name", "posts", "access_group", "public")

Table names are 1 to 256 characters long, with no control characters. /, !, *, # and % count as 3 characters each.

The examples on these pages build JSON with jsonOf(...) and read answers with the kotlinx.serialization.json accessors (jsonPrimitive, jsonObject, jsonArray). Every method that talks to the server is a suspend function, so call it from a coroutine (runBlocking, lifecycleScope.launch, and so on). See Getting Started.

WARNING

Writing the table as a plain string, "table" to "posts", is deprecated in getRecords and deleteRecords. It still means the public records of that table and logs a warning once (logger skapi). Always write jsonOf("name" to ..., "access_group" to ...).

Access groups ​

access_groupSame asWho can read the records
"public"0Anyone, signed in or not.
"authorized"1Any signed-in user.
2 to 98Users whose own access group is that number or higher.
"admin"99Admins and the project owner.
"private""*"The uploader, and the users they grant access to.

A user reads records in access groups up to their own, which is the access_group in their profile (skapi.user?.get("access_group")). The project owner sets it on skapi.com. Records come back with "public", "authorized", "admin", "private" or the number.

One table can hold records in several access groups. A query reads one table in one access group at a time:

kotlin
import com.skapi.*
import kotlinx.serialization.json.*

val skapi = Skapi("<Project ID>")

val publicNotes = skapi.getRecords(jsonOf("table" to jsonOf("name" to "notes", "access_group" to "public")))
val memberNotes = skapi.getRecords(jsonOf("table" to jsonOf("name" to "notes", "access_group" to "authorized")))
java
import com.skapi.java.SkapiJava;
import com.skapi.java.SkapiJson;
import java.util.Map;

SkapiJava skapi = new SkapiJava("<Project ID>");

Map<String, Object> publicNotes = skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "notes", "access_group", "public"))).get();
Map<String, Object> memberNotes = skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "notes", "access_group", "authorized"))).get();

Who can write ​

Signed-out callers can create records in "public" only, and must write "access_group" to "public" (or 0). Otherwise:

They try tocodemessage
name another access groupINVALID_PARAMETERUnsigned users have no access to records with access group.
leave access_group outINVALID_REQUESTPublic users can only post records to public tables.
update a recordINVALID_REQUESTPublic users cannot update existing records.
set a unique_idINVALID_REQUESTPublic users cannot set unique_id for records.
remove filesINVALID_REQUESTPublic users cannot remove files from records.

They cannot delete records either: deleteRecords needs a signed-in user. A record they create has a user_id that starts with anonymous:. It is temporary and names no user.

Signed-in users can post records to any access group up to their own, and to "private". They can update and delete only their own records, and not read-only ones. Admins can delete any record.

Reading while signed out ​

A signed-out caller can read only "public" records. Naming any other access group throws INVALID_PARAMETER: Unsigned users have no access to records with access group.

Require Login ​

When the project's Require Login setting is on (in the project settings on skapi.com), getRecords refuses signed-out callers before anything is sent:

kotlin
try {
    skapi.getRecords(jsonOf("table" to jsonOf("name" to "posts", "access_group" to "public")))
} catch (err: SkapiException) {
    if (err.code == "REQUIRE_LOGIN") println("Sign in first")
}
java
import com.skapi.SkapiException;
import java.util.concurrent.ExecutionException;

try {
    skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "posts", "access_group", "public"))).get();
} catch (ExecutionException e) {
    SkapiException err = (SkapiException) e.getCause();
    if ("REQUIRE_LOGIN".equals(err.getCode())) System.out.println("Sign in first");
}

The message is This project requires users to sign in before reading its database, so "getRecords" is not available to a signed-out visitor. Signed-in users are not affected, and neither are getTables, getTags, getIndexes and getUniqueId. The setting is a guard in the SDK, not an access rule on the server: data that must stay hidden from signed-out callers belongs in an access group above "public".

Next ​

skapi-kotlin 2.4.1