bknd-api-discovery

What this skill does

# API Discovery

Explore and understand Bknd's auto-generated REST API endpoints.

## Prerequisites

- Running Bknd instance (local or deployed)
- Access to admin panel (optional but helpful)
- Basic understanding of REST APIs

## When to Use UI Mode

- Browsing available entities and their fields
- Viewing schema structure visually
- Quick endpoint exploration via browser

**UI steps:** Admin Panel > Data > Entities

## When to Use Code Mode

- Listing all registered routes programmatically
- Understanding endpoint patterns for integration
- Debugging route registration issues
- Building API documentation

## Understanding Bknd's API Structure

Bknd auto-generates REST endpoints for all configured modules:

```
┌─────────────────────────────────────────────────────────────┐
│                    Bknd API Structure                       │
├─────────────────────────────────────────────────────────────┤
│  /api/data      → CRUD for all entities                     │
│  /api/auth      → Authentication (login, register, logout)  │
│  /api/media     → File uploads and serving                  │
│  /api/system    → System operations                         │
│  /flow          → Flow management and triggers              │
│  /admin         → Admin UI (if enabled)                     │
└─────────────────────────────────────────────────────────────┘
```

## Code Approach

### Step 1: List All Routes (CLI)

Use the debug command to list all registered routes:

```bash
bknd debug routes
```

**Output:**

```
GET     /admin/*
GET     /api/auth/me
POST    /api/auth/password/login
POST    /api/auth/logout
POST    /api/auth/register
GET     /api/data/:entity
POST    /api/data/:entity
GET     /api/data/:entity/:id
PATCH   /api/data/:entity/:id
DELETE  /api/data/:entity/:id
POST    /api/media/upload
GET     /api/media/:path
...
```

### Step 2: Data API Endpoints

All entities get CRUD endpoints automatically:

| Method | Path | Description | SDK Method |
|--------|------|-------------|------------|
| GET | `/api/data/:entity` | List records | `api.data.readMany(entity)` |
| POST | `/api/data/:entity/query` | List (complex query) | `api.data.readMany(entity, query)` |
| GET | `/api/data/:entity/:id` | Get single record | `api.data.readOne(entity, id)` |
| GET | `/api/data/:entity/:id/:ref` | Get related records | `api.data.readManyByReference(...)` |
| POST | `/api/data/:entity` | Create record(s) | `api.data.createOne/Many(entity, data)` |
| PATCH | `/api/data/:entity/:id` | Update single | `api.data.updateOne(entity, id, data)` |
| PATCH | `/api/data/:entity` | Update many | `api.data.updateMany(entity, where, data)` |
| DELETE | `/api/data/:entity/:id` | Delete single | `api.data.deleteOne(entity, id)` |
| DELETE | `/api/data/:entity` | Delete many | `api.data.deleteMany(entity, where)` |
| POST | `/api/data/:entity/fn/count` | Count records | `api.data.count(entity, where)` |
| POST | `/api/data/:entity/fn/exists` | Check existence | `api.data.exists(entity, where)` |

**Example: Explore posts entity**

```bash
# List all posts
curl http://localhost:7654/api/data/posts

# Get post by ID
curl http://localhost:7654/api/data/posts/1

# Get with query params
curl "http://localhost:7654/api/data/posts?limit=10&sort[created_at]=desc"

# Get with relations
curl "http://localhost:7654/api/data/posts?with[]=author&with[]=comments"

# Complex query via POST
curl -X POST http://localhost:7654/api/data/posts/query \
  -H "Content-Type: application/json" \
  -d '{"where": {"status": "published"}, "limit": 10}'
```

### Step 3: Auth API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/auth/me` | Current user info |
| POST | `/api/auth/:strategy/login` | Login (e.g., `/api/auth/password/login`) |
| POST | `/api/auth/register` | Register new user |
| POST | `/api/auth/logout` | Logout |
| GET | `/api/auth/:strategy/redirect` | OAuth redirect |
| GET | `/api/auth/:strategy/callback` | OAuth callback |

**Example:**

```bash
# Check current user
curl http://localhost:7654/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

# Login
curl -X POST http://localhost:7654/api/auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass123"}'

# Register
curl -X POST http://localhost:7654/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass123"}'
```

### Step 4: Media API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/media/upload` | Upload file |
| GET | `/api/media/:path` | Serve/download file |

**Example:**

```bash
# Upload file
curl -X POST http://localhost:7654/api/media/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]"

# Serve file
curl http://localhost:7654/api/media/uploads/image.png
```

### Step 5: Flow Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/flow` | List all flows |
| GET | `/flow/:name` | Get flow details |
| GET | `/flow/:name/run` | Manually run flow |
| * | Custom trigger path | HTTP trigger endpoints |

**Example:**

```bash
# List flows
curl http://localhost:7654/flow

# Run flow manually
curl http://localhost:7654/flow/my-flow/run
```

### Step 6: Programmatic Route Discovery

Access route information from your code:

```typescript
import { App } from "bknd";

const app = new App({ /* config */ });
await app.build();

// Get Hono server instance
const server = app.server;

// Routes are registered on the Hono instance
// Use bknd debug routes for listing
```

### Step 7: Discover Entity Schema

Query the system to understand available entities:

```typescript
import { Api } from "bknd";

const api = new Api({ host: "http://localhost:7654" });

// List available entities by checking which respond
const entities = ["posts", "users", "comments", "categories"];

for (const entity of entities) {
  const { ok } = await api.data.readMany(entity, { limit: 1 });
  if (ok) {
    console.log(`Entity exists: ${entity}`);
  }
}
```

### Step 8: Response Format Discovery

All endpoints return consistent response format:

**Success (list):**

```json
{
  "data": [
    { "id": 1, "title": "Post 1" },
    { "id": 2, "title": "Post 2" }
  ],
  "meta": {
    "total": 50,
    "limit": 20,
    "offset": 0
  }
}
```

**Success (single):**

```json
{
  "data": { "id": 1, "title": "Post 1" }
}
```

**Error:**

```json
{
  "error": {
    "message": "Record not found",
    "code": "NOT_FOUND"
  }
}
```

## UI Approach: Admin Panel

### Step 1: Access Admin Panel

Navigate to: `http://localhost:7654/admin`

### Step 2: Browse Entities

1. Click **Data** in sidebar
2. View list of all entities
3. Click entity to see:
   - All fields with types
   - Relationships
   - Sample data

### Step 3: View Entity Structure

Admin panel shows:
- Field names and types
- Required vs optional fields
- Default values
- Relation configurations

### Step 4: Test Queries

Admin panel provides:
- Data browser for each entity
- Filter/sort interface
- Create/edit forms
- Relationship navigation

## Query Parameter Reference

### Data Endpoints

| Parameter | Example | Description |
|-----------|---------|-------------|
| `limit` | `?limit=10` | Max records to return |
| `offset` | `?offset=20` | Skip N records |
| `sort[field]` | `?sort[created_at]=desc` | Sort by field |
| `where[field]` | `?where[status]=published` | Filter by field |
| `with[]` | `?with[]=author` | Include relation |
| `join[]` | `?join[]=author` | Join relation (same result) |
| `select[]` | `?select[]=id&select[]=title` | Select specific fields |

### Complex Queries (POST)

```bash
curl -X POST http://localhost:7654/api/data/posts/query \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "status": "published",
      "views": { "$gt": 100 }
    },
    "sort": { "created_at": "desc" },
    "limit": 10,
    "offset": 0,
    "with": ["author", "category"]
  }'
```

## SDK M