Users API

Overview

The Users API allows you to:

Retrieve user lists with pagination and filtering
Get individual user details
Create new users (Admin only)
Update user information (Admin only)
Delete users (Admin only)

Endpoints

GET /api/users

Retrieve a list of users with optional filtering, sorting, and pagination.

Permissions: Moderator or Admin

Query Parameters:

page (number, default: 1): Page number for pagination
limit (number, default: 10, max: 100): Number of items per page
q (string, optional): Search users by username or email
role (string, optional): Filter by role (user, moderator, admin)
active (boolean, optional): Filter by active status
sortBy (string, default: "username"): Sort field (username, email, role, createdAt)
sortOrder (string, default: "asc"): Sort order (asc, desc)

Example Request:

curl "https://api.nikode.ir/api/users?page=1&limit=10&role=moderator&active=true"

Example Response:

{
  "success": true,
  "message": "Users retrieved successfully",
  "data": [
    {
      "id": "user_1",
      "username": "admin_user",
      "email": "admin@example.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "admin",
      "avatar": "https://example.com/avatar.jpg",
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

GETTest GET /api/users

Retrieve users with filtering and pagination (requires moderator or admin role)

Query Parameters

page

limit

role

active

sortBy

sortOrder

POST /api/users

Create a new user.

Permissions: Admin only

Request Body:

{
  "username": "string (required)",
  "email": "string (required, email format)",
  "firstName": "string (required)",
  "lastName": "string (required)",
  "role": "string (optional, default: 'user')",
  "avatar": "string (optional, URL)",
  "isActive": "boolean (optional, default: true)"
}

Example Request:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_user",
    "email": "newuser@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": true
  }' \
  "https://api.nikode.ir/api/users"

Example Response:

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": "user_new_id",
    "username": "new_user",
    "email": "newuser@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

POSTTest POST /api/users

Create a new user (requires admin role)

Request Body

username *

email *

firstName *

lastName *

role

avatar

isActive

GET /api/users/[id]

Retrieve a specific user by ID.

Permissions: Public access

Path Parameters:

id (string, required): User ID

Example Request:

curl "https://api.nikode.ir/api/users/user_1"

Example Response:

{
  "success": true,
  "message": "User retrieved successfully",
  "data": {
    "id": "user_1",
    "username": "admin_user",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "admin",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

GETTest GET /api/users/[id]

Retrieve a specific user by ID

Path Parameters

id *

PUT /api/users/[id]

Update a user's information.

Permissions: Admin only

Path Parameters:

id (string, required): User ID

Request Body (all fields optional):

{
  "username": "string",
  "email": "string (email format)",
  "firstName": "string",
  "lastName": "string",
  "role": "string",
  "avatar": "string (URL)",
  "isActive": "boolean"
}

Example Request:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Updated",
    "lastName": "Name",
    "isActive": false
  }' \
  "https://api.nikode.ir/api/users/user_1"

Example Response:

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "id": "user_1",
    "username": "admin_user",
    "email": "admin@example.com",
    "firstName": "Updated",
    "lastName": "Name",
    "role": "admin",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

PUTTest PUT /api/users/[id]

Update a user (requires admin role)

Path Parameters

id *

Request Body

username

firstName

lastName

role

avatar

isActive

DELETE /api/users/[id]

Delete a user.

Permissions: Admin only

Path Parameters:

id (string, required): User ID

Note: Admin users cannot be deleted for security reasons.

Example Request:

curl -X DELETE "https://api.nikode.ir/api/users/user_2"

Example Response:

{
  "success": true,
  "message": "User deleted successfully",
  "data": {
    "id": "user_2",
    "username": "deleted_user",
    "email": "deleted@example.com",
    "firstName": "Deleted",
    "lastName": "User",
    "role": "user",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

DELETETest DELETE /api/users/[id]

Delete a user (requires admin role, cannot delete admin users)

Path Parameters

id *

Data Models

User Object

interface User {
  id: string;
  username: string;
  email: string;
  firstName: string;
  lastName: string;
  role: "user" | "moderator" | "admin";
  avatar: string;
  isActive: boolean;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

Create User Request

interface CreateUser {
  username: string;
  email: string;
  firstName: string;
  lastName: string;
  role?: "user" | "moderator" | "admin";
  avatar?: string;
  isActive?: boolean;
}

Update User Request

interface UpdateUser {
  username?: string;
  email?: string;
  firstName?: string;
  lastName?: string;
  role?: "user" | "moderator" | "admin";
  avatar?: string;
  isActive?: boolean;
}

Error Codes

Code	Status	Description
`FORBIDDEN`	403	Insufficient permissions for operation
`NOT_FOUND`	404	User not found
`VALIDATION_ERROR`	400	Invalid request data
`CONFLICT`	409	User with same username or email already exists
`INTERNAL_ERROR`	500	Server error

Rate Limits

User: 100 requests per hour
Moderator: 500 requests per hour
Admin: 1000 requests per hour

Examples

JavaScript/Node.js

// Get all users
const response = await fetch("/api/users");
const users = await response.json();

// Create a user
const newUser = await fetch("/api/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    username: "new_user",
    email: "newuser@example.com",
    firstName: "John",
    lastName: "Doe",
    role: "user",
    avatar: "https://example.com/avatar.jpg",
    isActive: true,
  }),
});

Python

import requests

# Get all users
response = requests.get('https://api.nikode.ir/api/users')
users = response.json()

# Create a user
new_user = requests.post(
    'https://api.nikode.ir/api/users',
    headers={
        'Content-Type': 'application/json'
    },
    json={
        'username': 'new_user',
        'email': 'newuser@example.com',
        'firstName': 'John',
        'lastName': 'Doe',
        'role': 'user',
        'avatar': 'https://example.com/avatar.jpg',
        'isActive': True
    }
)

cURL

# Get all users
curl "https://api.nikode.ir/api/users"

# Get users with filtering
curl "https://api.nikode.ir/api/users?role=moderator&active=true&sortBy=createdAt&sortOrder=desc"

# Create a user
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_user",
    "email": "newuser@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "avatar": "https://example.com/avatar.jpg",
    "isActive": true
  }' \
  "https://api.nikode.ir/api/users"

Users API

On this page