resources.md

Resources

Resources are the core building blocks of your Snaapi application. A resource represents a data entity, similar to a database table, that Snaapi automatically exposes as a fully functional REST API with role-based access control, validation, and event streaming.

Creating Your First Resource

The fastest way to create a resource is through the Admin Console:

1. Open the Admin Console and click Add Resource.
2. Enter a name for your resource (e.g., posts). Names must start with a letter or underscore, contain only alphanumeric characters and underscores, and be at most 100 characters long.
3. Add one or more fields. For each field, choose a name and type, then configure any properties like required or unique. See Fields for the full list of types and options.
4. Optionally add a description and configure permissions.
5. Click Save. Snaapi immediately generates REST API endpoints for your new resource. No deployment or restart is needed.

You can also create a resource programmatically by sending a POST request to the admin API:

{
  "name": "posts",
  "description": "Blog posts written by users",
  "fields": [
    { "name": "title", "type": "string", "required": true },
    { "name": "body", "type": "text" }
  ],
  "permissions": [
    { "role": "user", "action": "read", "fields": ["title", "body"] }
  ]
}

Common Patterns

Below are three resource definitions you can use as starting points for common use cases.

Blog Posts

A typical blog post with a title, body, auto-generated slug, and a status that controls visibility:

{
  "name": "posts",
  "description": "Blog posts",
  "fields": [
    { "name": "title", "type": "string", "required": true, "searchable": true },
    { "name": "body", "type": "text", "required": true },
    {
      "name": "slug",
      "type": "string",
      "unique": true,
      "generatedFrom": { "sourceField": "title", "transform": "slug" }
    },
    {
      "name": "status",
      "type": "enum",
      "enumValues": ["draft", "published", "archived"],
      "defaultValue": "draft"
    }
  ]
}

User Profiles

A lightweight profile that stores a bio, avatar URL, and personal website:

{
  "name": "profiles",
  "description": "Public user profiles",
  "fields": [
    { "name": "bio", "type": "text" },
    {
      "name": "avatar_url",
      "type": "string",
      "validations": [{ "rule": "url" }]
    },
    {
      "name": "website",
      "type": "string",
      "validations": [{ "rule": "url" }]
    }
  ]
}

Products

A product catalog entry with a name, price, SKU, and stock flag:

{
  "name": "products",
  "description": "Product catalog",
  "fields": [
    { "name": "name", "type": "string", "required": true, "searchable": true },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "validations": [{ "rule": "minValue", "value": 0 }]
    },
    { "name": "sku", "type": "string", "required": true, "unique": true },
    { "name": "in_stock", "type": "boolean", "defaultValue": true }
  ]
}

System Fields

Every resource automatically includes three system-managed fields that you do not need to define:

Field	Type	Description
id	uuid	Unique identifier, generated automatically
created_at	datetime	Timestamp set when the record is created
updated_at	datetime	Timestamp updated on every modification

System fields are always returned in API responses and can be referenced in permissions, filters, and sort operations. You cannot create custom fields with these reserved names.

Soft Delete

When enableSoftDelete is set to true, deleting a record does not remove it from the database. Instead, a deleted_at timestamp is set on the row. Soft- deleted records are excluded from normal queries but can be recovered or audited later.

{
  "name": "orders",
  "enableSoftDelete": true,
  "fields": [...]
}

By default, soft delete is disabled (false). You can toggle it when creating or updating a resource.

Enabling and Disabling Resources

Resources have an enabled flag (defaults to true). When a resource is disabled, its API endpoints stop accepting requests, effectively taking it offline without deleting the resource definition or its data.

{
  "name": "legacy_items",
  "enabled": false,
  "fields": [...]
}

Disabling a resource is useful for maintenance windows, staged rollouts, or deprecating endpoints while preserving the underlying data.