noob-components/.trellis/spec/plugs-api/index.md

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 API utilities	Filled
user	User API	Filled
role	Role API	Filled
permission	Permission API	Filled
dictionary	Dictionary API	Filled
config	Config API	Filled
log	Log API	Filled
public	Public API	Filled
buffer	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