API — Search

Tóm tắt endpoint

Method	Path	Mô tả	Auth	Rate limit
GET	`/api/v1/search/posts`	Search posts.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/search/username`	Search users.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/search/topic`	Search topics.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.

GET /api/v1/search/posts

GET Auth required apiLimiter

Endpoint này dùng để search posts. Gọi endpoint này khi client cần thao tác đúng phạm vi module search.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/search/posts \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "search",
    "endpoint": "/api/v1/search/posts"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Search đọc trực tiếp từ MySQL/Prisma.

GET /api/v1/search/username

GET Auth required apiLimiter

Endpoint này dùng để search users. Gọi endpoint này khi client cần thao tác đúng phạm vi module search.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/search/username \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "search",
    "endpoint": "/api/v1/search/username"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Search đọc trực tiếp từ MySQL/Prisma.

GET /api/v1/search/topic

GET Auth required apiLimiter

Endpoint này dùng để search topics. Gọi endpoint này khi client cần thao tác đúng phạm vi module search.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/search/topic \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "search",
    "endpoint": "/api/v1/search/topic"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Search đọc trực tiếp từ MySQL/Prisma.