API Endpoints

Snaapi automatically generates a full set of REST API endpoints for every enabled resource. All endpoints live under the /v1/:resourceName namespace and support authentication via session cookies, API keys, or admin tokens.

Base URL

All resource endpoints follow the pattern:

https://your-domain.com/v1/:resourceName

Replace :resourceName with the name of the resource you defined (e.g., posts, comments, orders).

List Records

Retrieve a paginated list of records, optionally filtered and sorted.

GET /v1/:resourceName

Response (200):

{
  "data": [
    {
      "id": "uuid",
      "title": "Hello",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "resource": "posts",
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

See Filtering and Pagination for query parameter details.

Get Single Record

Retrieve a single record by its ID.

GET /v1/:resourceName/:id

Response (200):

{
  "data": {
    "id": "uuid",
    "title": "Hello",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "meta": {
    "resource": "posts"
  }
}

Create Record

Create a new record. Send a JSON body with the fields defined on the resource.

POST /v1/:resourceName

Request body:

{
  "title": "My New Post",
  "body": "Content goes here"
}

Response (200):

{
  "data": {
    "id": "generated-uuid",
    "title": "My New Post",
    "body": "Content goes here",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "meta": {
    "resource": "posts"
  }
}

Update Record (Full Replace)

Replace all fields on an existing record.

PUT /v1/:resourceName/:id

Request body:

{
  "title": "Updated Title",
  "body": "Updated content"
}

Update Record (Partial)

Update only the specified fields on an existing record.

PATCH /v1/:resourceName/:id

Request body:

{
  "title": "Updated Title Only"
}

Delete Record

Delete a record by ID. If the resource has enableSoftDelete: true, the record is soft-deleted (a deleted_at timestamp is set) rather than permanently removed.

DELETE /v1/:resourceName/:id

Response (204 No Content): No response body.

Other Endpoints

Response Classes

Snaapi uses three standard response classes for all API responses.

ApiResponse

The wrapper for all successful responses. Returns JSON with Content-Type: application/json. Status 200 for data responses, 204 when data is null (e.g., after a delete).

ApiError

Returned when an operation fails. Contains a human-readable message, a machine-readable error code, and an optional errors array.

{
  "message": "Resource not found",
  "code": "RESOURCE_NOT_FOUND",
  "errors": []
}

ApiValidationError

Returned with status 400 when request data fails validation. Each entry in the errors array identifies the problematic field.

{
  "message": "Validation failed",
  "code": "INVALID_RESOURCE_DATA",
  "errors": [
    {
      "field": "title",
      "message": "Expected string, received number",
      "type": "string",
      "expected": "string",
      "received": "number"
    }
  ]
}

Error Codes

Client Errors

Server Errors

Admin Token Restrictions

Admin tokens are designed for management operations. On resource endpoints, they are restricted to read and delete operations only:

Attempting to create or update records with an admin token returns a 403 error with code ADMIN_TOKEN_NOT_ALLOWED. Use the dedicated admin API endpoints for write operations instead.