user_apis

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 19, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

user_apis

A weedbox module that registers REST API endpoints for user management. Provides Gin HTTP handlers for CRUD operations, password management, and user authentication.

Overview

On startup, this module registers the following routes under /apis/v1 on the HTTP server. All routes (except authenticate) are protected by RBAC permission checks.

Dependencies

Dependency Source Description
http_server.HTTPServer common-modules Gin HTTP server for route registration
user.UserManager user-modules/user User business logic
auth.AuthManager user-modules/auth Permission middleware

Module Registration

user_apis.Module("user_apis")

Endpoints

All endpoints are prefixed with /apis/v1.

List Users
GET /apis/v1/users

Permission: user.list

Query Parameters:

Parameter Type Default Description
page int 1 Page number
page_size int 10 Items per page
keywords string Search text (searches username, email, display_name)
search_fields string Comma-separated fields to search
orderby string Comma-separated fields to order by
order int -1 Sort order: 1 = ascending, -1 = descending
status string Filter by status (active, inactive, suspended)
role string Filter by role

Response:

{
  "total": 25,
  "page": 1,
  "page_size": 10,
  "total_pages": 3,
  "order_by": ["created_at"],
  "order": -1,
  "keywords": "",
  "users": [
    {
      "id": "...",
      "username": "admin",
      "email": "admin@localhost",
      "display_name": "System Administrator",
      "roles": ["admin"],
      "status": "active",
      "last_login_at": "2025-01-01T00:00:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}
Create User
POST /apis/v1/user

Permission: user.create

Request Body:

{
  "username": "john",
  "email": "john@example.com",
  "password": "secure-password",
  "display_name": "John Doe",
  "roles": ["user"],
  "status": "active"
}
Field Required Validation Description
username Yes min=3, max=255 Unique username
email Yes Valid email Unique email
password Yes min=8 Password (will be hashed)
display_name No Display name
roles No Role keys (default: ["user"])
status No active/inactive/suspended Status (default: active)

Response (201):

{
  "message": "user created successfully",
  "user": { "id": "...", "username": "john", ... }
}
Get User
GET /apis/v1/user/:id

Permission: user.read

Response (200):

{
  "user": { "id": "...", "username": "john", ... }
}
Update User
PUT /apis/v1/user/:id

Permission: user.update

Request Body: Same fields as Create (all optional). Only non-empty fields are updated.

Response (200):

{
  "message": "user updated successfully",
  "user": { "id": "...", "username": "john", ... }
}
Delete User
DELETE /apis/v1/user/:id

Permission: user.delete

Response (200):

{
  "message": "user deleted successfully"
}
Update Password
PUT /apis/v1/user/:id/password

Permission: user.password.update

Request Body:

{
  "current_password": "old-password",
  "new_password": "new-secure-password"
}
Field Required Validation Description
current_password Yes Current password for verification
new_password Yes min=8 New password

Response (200):

{
  "message": "password updated successfully"
}
Authenticate User
POST /apis/v1/user/authenticate

Permission: user.read

Request Body:

{
  "identifier": "john",
  "password": "secure-password"
}

Response (200):

{
  "success": true,
  "message": "Authentication successful",
  "user": { "id": "...", "username": "john", ... }
}

Error Responses

All error responses follow the format:

{
  "error": "Error description"
}
Status Condition
400 Invalid request body or parameters
401 Authentication required or invalid credentials
403 Insufficient permissions
404 User not found
409 Username or email already exists
500 Internal server error

Documentation

Index

Constants

View Source 
const ModuleName = "UserAPIs"

Variables

This section is empty.

Functions

func Module 

func Module(scope string) fx.Option

Types

type AuthenticateRequest 

type AuthenticateRequest struct {
	Body AuthenticateRequestBody
}

type AuthenticateRequestBody 

type AuthenticateRequestBody struct {
	Identifier string `json:"identifier" binding:"required"` // username or email
	Password   string `json:"password" binding:"required"`
}

type AuthenticateResponse 

type AuthenticateResponse struct {
	Success bool       `json:"success"`
	Message string     `json:"message"`
	User    *UserEntry `json:"user,omitempty"`
}

AuthenticateResponse authenticate response

type CreateRequest 

type CreateRequest struct {
	Body CreateRequestBody
}

type CreateRequestBody 

type CreateRequestBody struct {
	Username    string   `json:"username" binding:"required,min=3,max=255"`
	Email       string   `json:"email" binding:"required,email"`
	Password    string   `json:"password" binding:"required,min=8"`
	DisplayName string   `json:"display_name"`
	Roles       []string `json:"roles"` // Multiple roles
	Status      string   `json:"status" binding:"omitempty,oneof=active inactive suspended"`
}

type CreateResponse 

type CreateResponse struct {
	Message string     `json:"message"`
	User    *UserEntry `json:"user"`
}

CreateResponse create response

type DeleteRequest 

type DeleteRequest struct {
	URI DeleteRequestURI
}

type DeleteRequestURI 

type DeleteRequestURI struct {
	ID string `uri:"id" binding:"required"`
}

type DeleteResponse 

type DeleteResponse struct {
	Message string `json:"message"`
}

DeleteResponse delete response

type ErrorResponse added in v0.0.2 

type ErrorResponse struct {
	Error string `json:"error" example:"error message"`
}

ErrorResponse error response

type GetMeRequest added in v0.0.2 

type GetMeRequest struct{}

type GetMeResponse added in v0.0.2 

type GetMeResponse struct {
	User *UserEntry `json:"user"`
}

GetMeResponse self-service get me response

type GetRequest 

type GetRequest struct {
	URI GetRequestURI
}

type GetRequestURI 

type GetRequestURI struct {
	ID string `uri:"id" binding:"required"`
}

type GetResponse 

type GetResponse struct {
	User *UserEntry `json:"user"`
}

GetResponse get response

type ListRequest 

type ListRequest struct {
	Query ListRequestQuery
}

type ListRequestQuery 

type ListRequestQuery struct {
	Page         int    `form:"page"`
	PageSize     int    `form:"page_size"`
	Keywords     string `form:"keywords"`
	SearchFields string `form:"search_fields"`
	OrderBy      string `form:"orderby"`
	Order        int    `form:"order"`
	Status       string `form:"status"`
	Role         string `form:"role"`
}

type ListResponse 

type ListResponse struct {
	Total      int64        `json:"total"`
	Page       int          `json:"page"`
	PageSize   int          `json:"page_size"`
	TotalPages int          `json:"total_pages"`
	OrderBy    []string     `json:"order_by"`
	Order      int          `json:"order"`
	Keywords   string       `json:"keywords,omitempty"`
	Users      []*UserEntry `json:"users"`
}

ListResponse list response

type Params 

type Params struct {
	weedbox.Params
	HTTPServer *http_server.HTTPServer
	User       *user.UserManager `name:"user"`
	Auth       *auth.AuthManager `name:"auth"`
}

type UpdateMeRequest added in v0.0.2 

type UpdateMeRequest struct {
	Body UpdateMeRequestBody
}

type UpdateMeRequestBody added in v0.0.2 

type UpdateMeRequestBody struct {
	Username    string `json:"username" binding:"omitempty,min=3,max=255"`
	Email       string `json:"email" binding:"omitempty,email"`
	DisplayName string `json:"display_name"`
}

type UpdateMeResponse added in v0.0.2 

type UpdateMeResponse struct {
	Message string     `json:"message"`
	User    *UserEntry `json:"user"`
}

UpdateMeResponse self-service update me response

type UpdateMyPasswordRequest added in v0.0.2 

type UpdateMyPasswordRequest struct {
	Body UpdateMyPasswordRequestBody
}

type UpdateMyPasswordRequestBody added in v0.0.2 

type UpdateMyPasswordRequestBody struct {
	CurrentPassword string `json:"current_password" binding:"required"`
	NewPassword     string `json:"new_password" binding:"required,min=8"`
}

type UpdateMyPasswordResponse added in v0.0.2 

type UpdateMyPasswordResponse struct {
	Message string `json:"message"`
}

UpdateMyPasswordResponse self-service update my password response

type UpdatePasswordRequest 

type UpdatePasswordRequest struct {
	URI  UpdatePasswordRequestURI
	Body UpdatePasswordRequestBody
}

type UpdatePasswordRequestBody 

type UpdatePasswordRequestBody struct {
	NewPassword string `json:"new_password" binding:"required,min=8"`
}

type UpdatePasswordRequestURI 

type UpdatePasswordRequestURI struct {
	ID string `uri:"id" binding:"required"`
}

type UpdatePasswordResponse 

type UpdatePasswordResponse struct {
	Message string `json:"message"`
}

UpdatePasswordResponse update password response (admin reset)

type UpdateRequest 

type UpdateRequest struct {
	URI  UpdateRequestURI
	Body UpdateRequestBody
}

type UpdateRequestBody 

type UpdateRequestBody struct {
	Username    string   `json:"username" binding:"omitempty,min=3,max=255"`
	Email       string   `json:"email" binding:"omitempty,email"`
	DisplayName string   `json:"display_name"`
	Roles       []string `json:"roles"` // Multiple roles
	Status      string   `json:"status" binding:"omitempty,oneof=active inactive suspended"`
}

type UpdateRequestURI 

type UpdateRequestURI struct {
	ID string `uri:"id" binding:"required"`
}

type UpdateResponse 

type UpdateResponse struct {
	Message string     `json:"message"`
	User    *UserEntry `json:"user"`
}

UpdateResponse update response

type UserAPIs 

type UserAPIs struct {
	weedbox.Module[*Params]
}

func (*UserAPIs) InitDefaultConfigs 

func (m *UserAPIs) InitDefaultConfigs()

func (*UserAPIs) OnStart 

func (m *UserAPIs) OnStart(ctx context.Context) error

func (*UserAPIs) OnStop 

func (m *UserAPIs) OnStop(ctx context.Context) error

type UserEntry 

type UserEntry struct {
	ID          string   `json:"id"`
	Username    string   `json:"username"`
	Email       string   `json:"email"`
	DisplayName string   `json:"display_name"`
	Roles       []string `json:"roles"`
	Status      string   `json:"status"`
	LastLoginAt *string  `json:"last_login_at,omitempty"`
	CreatedAt   string   `json:"created_at"`
	UpdatedAt   string   `json:"updated_at"`
}

UserEntry user item in API response

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.