# Plugs API Guidelines

> Typed API functions wrapping HTTP calls.

---

## Overview

This directory documents the API layer in `plugs/api/`.

---

## Guidelines Index

| Guide | Description | Status |
|-------|-------------|--------|
| [base](./base.md) | Base API utilities | Filled |
| [user](./user.md) | User API | Filled |
| [role](./role.md) | Role API | Filled |
| [permission](./permission.md) | Permission API | Filled |
| [dictionary](./dictionary.md) | Dictionary API | Filled |
| [config](./config.md) | Config API | Filled |
| [log](./log.md) | Log API | Filled |
| [public](./public.md) | Public API | Filled |
| [buffer](./buffer.md) | Buffer API | Filled |

---

## Common Patterns

### HTTP Methods

| Method | Function | Purpose |
|--------|----------|---------|
| GET | `get`, `queryPage`, `queryList` | Read operations |
| POST | `save`, `add` | Create operations |
| PUT | `update`, `set` | Update operations |
| DELETE | `deleteById`, `del`, `clean` | Delete operations |

### Response Handling

All API functions return `Promise` and handle errors by resolving with falsy values instead of rejecting:
- `resolve(false)` - Operation failed
- `resolve([])` - List/query returned nothing
- `resolve({})` - Get by ID returned nothing

### URL Patterns

- **Standard**: `resource` (e.g., `user`, `role`, `permission`)
- **Public**: `public/resource` (no auth required)
- **With ID**: `resource/id` (get, update, delete single item)

### Function Naming

| Pattern | Example | Description |
|---------|---------|-------------|
| `list(example?)` | `role.list({ status: 1 })` | List with optional filter |
| `add(item)` | `user.add({ username: 'x' })` | Create new |
| `set(item)` | `config.set({ key: 'x', value: 'y' })` | Update existing |
| `del(item)` | `role.del({ roleCode: 'ADMIN' })` | Delete (passes ID field) |
| `getValue(key)` | `config.getValue('app.name')` | Get single value |

---

## HTTP Layer

See `plugs/http/axios.ts` for the underlying HTTP client configuration.

---

**Language**: English