User Relations Endpoints

Account Privacy APIs
Follow System APIs
Privacy Control API

Account Privacy APIs

Author: Kibuti, Backend Developer
Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Account Privacy API allows users to manage their account privacy settings, controlling whether their account is private or public. Private accounts require follow request approval before users can see their content and follow them.

Hints:

All endpoints require authentication via Bearer token
Privacy settings are automatically created with default values (public account) on first access
Changing privacy settings does not affect existing followers
Private accounts require follow request approval for new followers

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)
PATCH - PATCH - Orange (Partial updates)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Get Privacy Settings

Purpose: Retrieve the current privacy settings for the authenticated user's account

Endpoint: GET {base_url}/e-social/privacy/account

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Privacy settings retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "isPrivate": false,
    "createdAt": "2025-01-15T08:20:30",
    "updatedAt": "2025-12-11T10:30:45"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the privacy settings record (UUID format)
userId	Unique identifier of the user who owns these settings (UUID format)
isPrivate	Boolean flag indicating if the account is private (true) or public (false)
createdAt	Timestamp when the privacy settings were first created (ISO 8601 format)
updatedAt	Timestamp when the privacy settings were last modified (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Unauthorized - Token Issues (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Unauthorized - Missing Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-12-11T10:30:45",
  "data": "Authentication token is required"
}

2. Update Privacy Settings

Purpose: Update the privacy settings for the authenticated user's account (switch between private and public)

Endpoint: PUT {base_url}/e-social/privacy/account

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "isPrivate": true
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
isPrivate	boolean	Yes	Flag to set account as private (true) or public (false)	Must not be null

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Privacy settings updated successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "isPrivate": true,
    "createdAt": "2025-01-15T08:20:30",
    "updatedAt": "2025-12-11T10:30:45"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the privacy settings record (UUID format)
userId	Unique identifier of the user who owns these settings (UUID format)
isPrivate	Boolean flag indicating if the account is private (true) or public (false)
createdAt	Timestamp when the privacy settings were first created (ISO 8601 format)
updatedAt	Timestamp when the privacy settings were last modified (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "isPrivate": "must not be null"
  }
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "isPrivate": "must not be null"
  }
}

Unauthorized - Token Issues (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/PUT request
401 Unauthorized: Authentication required/failed
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-12-11T14:30:00Z)
IDs: UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)

Follow System APIs

Author: Josh, Lead Backend Developer
Last Updated: 2025-12-20
Version: v1.1

Base URL: https://api.nexgate.com/api/v1

Short Description: The Follow System API manages user relationships including following/unfollowing users, handling follow requests for private accounts, retrieving followers and following lists, and discovering featured users. It supports both immediate follows (public accounts) and pending follow requests (private accounts). The system intelligently tracks mutual relationships and provides contextual follow/unfollow buttons based on the authenticated user's relationship with other users.

Hints:

All endpoints require authentication via Bearer token
Following a private account creates a PENDING follow request that requires acceptance
Following a public account creates an ACCEPTED follow immediately
Featured users are sorted by follower count and exclude users you already follow
Pagination is 1-indexed (page=1 for first page)
Default page size is 20 items
Follower/Following lists include relationship indicators (followsYou, youFollow) for smart button rendering

How The Follow System Works

Relationship Context Logic

The Follow System provides intelligent relationship tracking between the authenticated user (you) and listed users across different profile views:

1. Your Own Followers List (`/followers/{yourUserId}`)

Shows users who follow you
Each follower includes:
- followsYou: Always true (they follow you)
- youFollow: Whether you follow them back
Button Logic:
- youFollow: false → Show "Follow Back" button
- youFollow: true → Show "Following" button

2. Your Own Following List (`/following/{yourUserId}`)

Shows users you follow
Each user includes:
- followsYou: Whether they follow you back (mutual relationship)
- youFollow: Always true (you follow them)
UI Logic:
- followsYou: true → Display "Follows You" badge
- Always show "Following" button (can unfollow)

3. Friend's Followers List (`/followers/{friendUserId}`)

Shows users who follow your friend
Each follower includes:
- followsYou: Whether this follower follows you (authenticated user)
- youFollow: Whether you follow this follower
Button Logic:
- followsYou: true AND youFollow: false → Show "Follow Back"
- youFollow: true → Show "Following"
- Both false → Show "Follow"

4. Friend's Following List (`/following/{friendUserId}`)

Shows users your friend follows
Each user includes:
- followsYou: Whether this user follows you (authenticated user)
- youFollow: Whether you follow this user
Button Logic:
- followsYou: true AND youFollow: false → Show "Follow Back"
- youFollow: true → Show "Following"
- Both false → Show "Follow"

Privacy & Status Rules

Private Accounts:

Follow requests enter PENDING status
Require manual acceptance by the account owner
Can be accepted or declined

Public Accounts:

Follows are immediately ACCEPTED
No manual approval needed

Blocking Behavior:

Blocking a user removes all follow relationships (bidirectional)
Blocked users cannot follow you or see your content

Key Principle: All relationship indicators (followsYou, youFollow) are always calculated relative to the authenticated user, regardless of whose profile is being viewed.

UI Implementation Best Practices

Button State Management

The follow system uses a single button that changes state based on the relationship context. This follows industry standards (Twitter/X, Instagram, LinkedIn).

Button Logic by Relationship State:

if (youFollow) {
  // Button: "Following"
  // Action: Click to unfollow (with confirmation)
  // Style: Secondary/outlined button
} else if (followsYou) {
  // Button: "Follow Back"
  // Action: Click to follow immediately (no confirmation)
  // Style: Primary/solid button
} else {
  // Button: "Follow"
  // Action: Click to follow immediately (no confirmation)
  // Style: Primary/solid button
}

Why Single Button Design:

✅ Advantages:

Clean, uncluttered interface
Clear current state indication
Industry-standard pattern
Saves screen space
Intuitive user experience

❌ Avoid:

Separate "Unfollow" button (clutters UI)
Multiple buttons for same relationship
Ambiguous action labels

Confirmation Dialog Best Practices

Show confirmation ONLY for destructive actions:

Unfollow Action (Destructive):

User clicks "Following" button
↓
Show confirmation modal:
"Unfollow @username?"
[Cancel] [Unfollow]
↓
On confirm: Call DELETE /e-social/follows/{userId}

Follow/Follow Back Actions (Constructive):

User clicks "Follow" or "Follow Back" button
↓
Immediately call POST /e-social/follows/{userId}
No confirmation needed

Rationale:

Unfollowing removes an existing connection (requires confirmation)
Following creates a new connection (no barrier needed)
Matches user expectations from major platforms

Visual States & Feedback

Button States:

State	Label	Style	On Click
Not Following	"Follow"	Primary/Solid	Follow immediately
Mutual Follow Possible	"Follow Back"	Primary/Solid	Follow immediately
Currently Following	"Following"	Secondary/Outlined	Show unfollow confirmation
Pending Request	"Requested"	Secondary/Disabled	Cancel request (optional)

Loading States:

Show spinner on button during API call
Disable button to prevent double-clicks
Optimistic UI update (change button immediately, rollback on error)

Error Handling:

Show toast/snackbar on API errors
Revert button state on failure
Clear error messages (e.g., "Failed to follow user. Try again.")

Additional UI Elements

Badges:

Show "Follows You" badge when followsYou: true in Following list
Display badge near username, not on button
Use subtle styling (gray text or small pill)

Private Account Indicators:

Show lock icon for private accounts
Update button to "Request" for private accounts
After clicking, change to "Requested" state

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - Green (Safe, read-only operations)
POST - Blue (Create new resources)
DELETE - Red (Remove resources)

Endpoints

1. Follow User

Purpose: Follow a user or create a follow request if the target account is private

Endpoint: POST {base_url}/e-social/follows/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to follow	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User followed successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440011",
    "followerId": "123e4567-e89b-12d3-a456-426614174000",
    "followingId": "987e6543-e21b-12d3-a456-426614174999",
    "follower": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "john_doe",
      "firstName": "John",
      "lastName": "Doe",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/john_doe.jpg"],
      "isVerified": true
    },
    "following": {
      "id": "987e6543-e21b-12d3-a456-426614174999",
      "userName": "jane_smith",
      "firstName": "Jane",
      "lastName": "Smith",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/jane_smith.jpg"],
      "isVerified": false
    },
    "status": "ACCEPTED",
    "createdAt": "2025-12-11T10:30:45"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the follow relationship (UUID format)
followerId	UUID of the user who initiated the follow
followingId	UUID of the user being followed
follower	Object containing summary information about the follower user
follower.id	UUID of the follower user
follower.userName	Username of the follower
follower.firstName	First name of the follower
follower.lastName	Last name of the follower
follower.profilePictureUrls	Array of profile picture URLs for the follower
follower.isVerified	Boolean indicating if the follower account is verified
following	Object containing summary information about the user being followed
following.id	UUID of the user being followed
following.userName	Username of the user being followed
following.firstName	First name of the user being followed
following.lastName	Last name of the user being followed
following.profilePictureUrls	Array of profile picture URLs for the user being followed
following.isVerified	Boolean indicating if the followed account is verified
status	Follow status - "ACCEPTED" for public accounts, "PENDING" for private accounts
createdAt	Timestamp when the follow relationship was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot follow yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot follow yourself"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Cannot follow yourself, already following this user, or invalid request data
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to follow not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Self Follow (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot follow yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot follow yourself"
}

Bad Request - Already Following (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Already following this user",
  "action_time": "2025-12-11T10:30:45",
  "data": "Already following this user"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

2. Unfollow User

Purpose: Remove a follow relationship with another user

Endpoint: DELETE {base_url}/e-social/follows/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to unfollow	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User unfollowed successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Success Response Fields:

Field	Description
data	Always null for this endpoint

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to unfollow not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

3. Accept Follow Request

Purpose: Accept a pending follow request from another user

Endpoint: POST {base_url}/e-social/follows/requests/{followId}/accept

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
followId	string	Yes	UUID of the follow request to accept	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Follow request accepted",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440011",
    "followerId": "987e6543-e21b-12d3-a456-426614174999",
    "followingId": "123e4567-e89b-12d3-a456-426614174000",
    "follower": {
      "id": "987e6543-e21b-12d3-a456-426614174999",
      "userName": "jane_smith",
      "firstName": "Jane",
      "lastName": "Smith",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/jane_smith.jpg"],
      "isVerified": false
    },
    "following": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "john_doe",
      "firstName": "John",
      "lastName": "Doe",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/john_doe.jpg"],
      "isVerified": true
    },
    "status": "ACCEPTED",
    "createdAt": "2025-12-11T09:15:30"
  }
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Follow request is not pending
401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Follow request not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

4. Decline Follow Request

Purpose: Decline a pending follow request from another user

Endpoint: DELETE {base_url}/e-social/follows/requests/{followId}/decline

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
followId	string	Yes	UUID of the follow request to decline	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Follow request declined",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Follow request is not pending
401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Follow request not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

5. Get Followers

Purpose: Retrieve the complete list of users following a specified user with relationship context

Endpoint: GET {base_url}/e-social/follows/followers/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user whose followers to retrieve	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Followers retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440011",
      "user": {
        "id": "987e6543-e21b-12d3-a456-426614174999",
        "userName": "jane_smith",
        "firstName": "Jane",
        "lastName": "Smith",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/jane_smith.jpg"],
        "isVerified": false
      },
      "status": "ACCEPTED",
      "createdAt": "2025-12-10T14:20:15",
      "followsYou": true,
      "youFollow": false
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440022",
      "user": {
        "id": "111e1111-e11b-11d1-a111-111111111111",
        "userName": "bob_wilson",
        "firstName": "Bob",
        "lastName": "Wilson",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/bob_wilson.jpg"],
        "isVerified": true
      },
      "status": "ACCEPTED",
      "createdAt": "2025-12-09T08:45:30",
      "followsYou": true,
      "youFollow": true
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of follower objects
data[].id	Unique identifier for the follow relationship (UUID format)
data[].user	Object containing information about the follower user
data[].user.id	UUID of the follower user
data[].user.userName	Username of the follower
data[].user.firstName	First name of the follower
data[].user.lastName	Last name of the follower
data[].user.profilePictureUrls	Array of profile picture URLs for the follower
data[].user.isVerified	Boolean indicating if the follower account is verified
data[].status	Follow status - always "ACCEPTED" for this endpoint
data[].createdAt	Timestamp when the follow relationship was created (ISO 8601 format)
data[].followsYou	NEW: Does this follower follow the authenticated user?
data[].youFollow	NEW: Does the authenticated user follow this follower back?

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: User not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

6. Get Following

Purpose: Retrieve the complete list of users that a specified user is following with relationship context

Endpoint: GET {base_url}/e-social/follows/following/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user whose following list to retrieve	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Following retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440011",
      "user": {
        "id": "222e2222-e22b-22d2-a222-222222222222",
        "userName": "alice_johnson",
        "firstName": "Alice",
        "lastName": "Johnson",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/alice_johnson.jpg"],
        "isVerified": true
      },
      "status": "ACCEPTED",
      "createdAt": "2025-12-08T16:30:00",
      "followsYou": true,
      "youFollow": true
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of following objects
data[].id	Unique identifier for the follow relationship (UUID format)
data[].user	Object containing information about the followed user
data[].user.id	UUID of the followed user
data[].user.userName	Username of the followed user
data[].user.firstName	First name of the followed user
data[].user.lastName	Last name of the followed user
data[].user.profilePictureUrls	Array of profile picture URLs for the followed user
data[].user.isVerified	Boolean indicating if the followed account is verified
data[].status	Follow status - always "ACCEPTED" for this endpoint
data[].createdAt	Timestamp when the follow relationship was created (ISO 8601 format)
data[].followsYou	NEW: Does this user follow the authenticated user back?
data[].youFollow	NEW: Does the authenticated user follow this user?

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: User not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

7. Get Followers (Paginated)

Purpose: Retrieve a paginated list of users following a specified user with relationship context

Endpoint: GET {base_url}/e-social/follows/followers/{userId}/paged

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user whose followers to retrieve	Must be valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Followers retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440011",
        "user": {
          "id": "987e6543-e21b-12d3-a456-426614174999",
          "userName": "jane_smith",
          "firstName": "Jane",
          "lastName": "Smith",
          "profilePictureUrls": ["https://cdn.nexgate.com/profiles/jane_smith.jpg"],
          "isVerified": false
        },
        "status": "ACCEPTED",
        "createdAt": "2025-12-10T14:20:15",
        "followsYou": true,
        "youFollow": false
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "numberOfElements": 1,
    "empty": false
  }
}

Success Response Fields:

Field	Description
data.content	Array of follower objects for the current page (includes `followsYou` and `youFollow` fields)
data.content[].followsYou	NEW: Does this follower follow the authenticated user?
data.content[].youFollow	NEW: Does the authenticated user follow this follower back?
data.pageable	Pagination metadata
data.totalPages	Total number of pages available
data.totalElements	Total number of followers
data.first	Boolean indicating if this is the first page
data.last	Boolean indicating if this is the last page
data.size	Page size
data.number	Current page number (0-indexed)
data.numberOfElements	Number of elements in current page
data.empty	Boolean indicating if the page is empty

8. Get Following (Paginated)

Purpose: Retrieve a paginated list of users that a specified user is following with relationship context

Endpoint: GET {base_url}/e-social/follows/following/{userId}/paged

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user whose following list to retrieve	Must be valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Following retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440011",
        "user": {
          "id": "222e2222-e22b-22d2-a222-222222222222",
          "userName": "alice_johnson",
          "firstName": "Alice",
          "lastName": "Johnson",
          "profilePictureUrls": ["https://cdn.nexgate.com/profiles/alice_johnson.jpg"],
          "isVerified": true
        },
        "status": "ACCEPTED",
        "createdAt": "2025-12-08T16:30:00",
        "followsYou": true,
        "youFollow": true
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "numberOfElements": 1,
    "empty": false
  }
}

Success Response Fields:

Field	Description
data.content	Array of following objects for the current page (includes `followsYou` and `youFollow` fields)
data.content[].followsYou	NEW: Does this user follow the authenticated user back?
data.content[].youFollow	NEW: Does the authenticated user follow this user?
data.pageable	Pagination metadata
data.totalPages	Total number of pages available
data.totalElements	Total number of users being followed
data.first	Boolean indicating if this is the first page
data.last	Boolean indicating if this is the last page
data.size	Page size
data.number	Current page number (0-indexed)
data.numberOfElements	Number of elements in current page
data.empty	Boolean indicating if the page is empty

9. Get Pending Follow Requests

Purpose: Retrieve all pending follow requests for the authenticated user (requests they need to approve)

Endpoint: GET {base_url}/e-social/follows/requests/pending

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Pending requests retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440011",
      "user": {
        "id": "333e3333-e33b-33d3-a333-333333333333",
        "userName": "charlie_brown",
        "firstName": "Charlie",
        "lastName": "Brown",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/charlie_brown.jpg"],
        "isVerified": false
      },
      "status": "PENDING",
      "createdAt": "2025-12-11T09:15:30",
      "followsYou": false,
      "youFollow": false
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of pending follow request objects
data[].id	Unique identifier for the follow relationship (UUID format)
data[].user	Object containing information about the user requesting to follow
data[].status	Follow status - always "PENDING" for this endpoint
data[].createdAt	Timestamp when the follow request was created (ISO 8601 format)
data[].followsYou	NEW: Does this requester follow the authenticated user?
data[].youFollow	NEW: Does the authenticated user follow this requester?

10. Get User Stats

Purpose: Retrieve follower, following, and pending request counts for a specified user

Endpoint: GET {base_url}/e-social/follows/stats/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user whose stats to retrieve	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User stats retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "followersCount": 1250,
    "followingCount": 487,
    "pendingRequestsCount": 15
  }
}

Success Response Fields:

Field	Description
userId	UUID of the user these stats belong to
followersCount	Total number of accepted followers for this user
followingCount	Total number of users this user is following (accepted follows only)
pendingRequestsCount	Total number of pending follow requests for this user

11. Check Follow Status

Purpose: Check if the authenticated user is following a specified user

Endpoint: GET {base_url}/e-social/follows/check/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to check follow status for	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Follow status checked",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "userId": "987e6543-e21b-12d3-a456-426614174999",
    "isFollowing": true
  }
}

Success Response Fields:

Field	Description
userId	UUID of the user being checked
isFollowing	Boolean indicating if the authenticated user is following this user (includes pending and accepted follows)

12. Get Featured Users

Purpose: Retrieve a list of suggested users to follow, sorted by follower count, excluding users already followed by the authenticated user

Endpoint: GET {base_url}/e-social/follows/featured

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
limit	integer	No	Maximum number of featured users to return	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Featured users retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "555e5555-e55b-55d5-a555-555555555555",
      "userName": "tech_guru",
      "firstName": "Sarah",
      "lastName": "Martinez",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/tech_guru.jpg"],
      "isVerified": true,
      "followersCount": 125000,
      "followsMe": false
    },
    {
      "id": "666e6666-e66b-66d6-a666-666666666666",
      "userName": "travel_explorer",
      "firstName": "Mike",
      "lastName": "Chen",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/travel_explorer.jpg"],
      "isVerified": true,
      "followersCount": 98500,
      "followsMe": true
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of featured user objects
data[].id	UUID of the featured user
data[].userName	Username of the featured user
data[].firstName	First name of the featured user
data[].lastName	Last name of the featured user
data[].profilePictureUrls	Array of profile picture URLs for the featured user
data[].isVerified	Boolean indicating if the featured account is verified
data[].followersCount	Total number of followers the featured user has
data[].followsMe	Boolean indicating if this featured user follows the authenticated user

13. Get Featured Users (Paginated)

Purpose: Retrieve a paginated list of suggested users to follow, sorted by follower count, excluding users already followed by the authenticated user

Endpoint: GET {base_url}/e-social/follows/featured/paged

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Featured users retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "id": "555e5555-e55b-55d5-a555-555555555555",
        "userName": "tech_guru",
        "firstName": "Sarah",
        "lastName": "Martinez",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/tech_guru.jpg"],
        "isVerified": true,
        "followersCount": 125000,
        "followsMe": false
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "last": false,
    "totalPages": 5,
    "totalElements": 87,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "numberOfElements": 20,
    "empty": false
  }
}

Success Response Fields:

Field	Description
data.content	Array of featured user objects for the current page
data.content[].id	UUID of the featured user
data.content[].userName	Username of the featured user
data.content[].firstName	First name of the featured user
data.content[].lastName	Last name of the featured user
data.content[].profilePictureUrls	Array of profile picture URLs
data.content[].isVerified	Boolean indicating if account is verified
data.content[].followersCount	Total number of followers
data.content[].followsMe	Boolean indicating if this user follows the authenticated user
data.pageable	Pagination metadata
data.totalPages	Total number of pages available
data.totalElements	Total number of featured users
data.first	Boolean indicating if this is the first page
data.last	Boolean indicating if this is the last page
data.size	Page size
data.number	Current page number (0-indexed)
data.numberOfElements	Number of elements in current page
data.empty	Boolean indicating if the page is empty

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/POST/DELETE request
400 Bad Request: Invalid request data or business rule violation
401 Unauthorized: Authentication required/failed
404 Not Found: Resource not found
500 Internal Server Error: Server error

Authentication

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-12-11T14:30:00Z)
IDs: UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)
Pagination: 1-indexed pages (page=1 for first page), default size=20

Relationship Field Reference

Field	Meaning
`followsYou`	Does this user follow you (authenticated user)?
`youFollow`	Do you (authenticated user) follow this user?

These fields enable smart UI rendering:

Show "Follow Back" when followsYou: true and youFollow: false
Show "Follows You" badge when followsYou: true
Show "Following" when youFollow: true
Show "Follow" when both are false

Version History

v1.1 (2025-12-20)

Added relationship context fields (followsYou, youFollow) to all follower/following endpoints
Added "How The Follow System Works" section with detailed relationship logic
Added "UI Implementation Best Practices" section with button state management and confirmation patterns
Updated all response samples to include new relationship fields
Enhanced documentation with button logic examples and visual state guidelines

v1.0 (2025-12-11)

Initial release
All core follow system endpoints
Basic follower/following management
Featured users discovery

Privacy Control API

Author: Kibuti, Backend Developer
Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Privacy Control API allows users to block and mute other users to control their social interactions. Blocking removes all follow relationships and prevents future interactions, while muting hides content without breaking the follow relationship. These features give users granular control over their social experience.

Hints:

All endpoints require authentication via Bearer token
Blocking a user automatically unfollows both users from each other
Muting only affects content visibility and does not break follow relationships
Users cannot block or mute themselves
Blocked and muted lists are retrieved in reverse chronological order (newest first)

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Block User

Purpose: Block a user to prevent all interactions and remove existing follow relationships

Endpoint: POST {base_url}/e-social/privacy-control/block/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to block	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User blocked successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440033",
    "user": {
      "id": "777e7777-e77b-77d7-a777-777777777777",
      "userName": "spam_account",
      "firstName": "Spam",
      "lastName": "Account",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/spam_account.jpg"],
      "isVerified": false
    },
    "createdAt": "2025-12-11T10:30:45"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the block record (UUID format)
user	Object containing information about the blocked user
user.id	UUID of the blocked user
user.userName	Username of the blocked user
user.firstName	First name of the blocked user
user.lastName	Last name of the blocked user
user.profilePictureUrls	Array of profile picture URLs for the blocked user
user.isVerified	Boolean indicating if the blocked account is verified
createdAt	Timestamp when the block was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot block yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot block yourself"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Cannot block yourself or user already blocked
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to block not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Self Block (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot block yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot block yourself"
}

Bad Request - Already Blocked (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User already blocked",
  "action_time": "2025-12-11T10:30:45",
  "data": "User already blocked"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

2. Unblock User

Purpose: Remove a block on a previously blocked user

Endpoint: DELETE {base_url}/e-social/privacy-control/unblock/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to unblock	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User unblocked successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Success Response Fields:

Field	Description
data	Always null for this endpoint

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to unblock not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

3. Mute User

Purpose: Mute a user to hide their content without breaking the follow relationship

Endpoint: POST {base_url}/e-social/privacy-control/mute/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to mute	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User muted successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440044",
    "user": {
      "id": "888e8888-e88b-88d8-a888-888888888888",
      "userName": "noisy_user",
      "firstName": "Noisy",
      "lastName": "User",
      "profilePictureUrls": ["https://cdn.nexgate.com/profiles/noisy_user.jpg"],
      "isVerified": true
    },
    "createdAt": "2025-12-11T10:30:45"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the mute record (UUID format)
user	Object containing information about the muted user
user.id	UUID of the muted user
user.userName	Username of the muted user
user.firstName	First name of the muted user
user.lastName	Last name of the muted user
user.profilePictureUrls	Array of profile picture URLs for the muted user
user.isVerified	Boolean indicating if the muted account is verified
createdAt	Timestamp when the mute was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot mute yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot mute yourself"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Cannot mute yourself or user already muted
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to mute not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Self Mute (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot mute yourself",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot mute yourself"
}

Bad Request - Already Muted (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User already muted",
  "action_time": "2025-12-11T10:30:45",
  "data": "User already muted"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

4. Unmute User

Purpose: Remove a mute on a previously muted user

Endpoint: DELETE {base_url}/e-social/privacy-control/unmute/{userId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
userId	string	Yes	UUID of the user to unmute	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "User unmuted successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Success Response Fields:

Field	Description
data	Always null for this endpoint

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: User to unmute not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "User not found"
}

5. Get Blocked Users

Purpose: Retrieve the complete list of users blocked by the authenticated user

Endpoint: GET {base_url}/e-social/privacy-control/blocked

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Blocked users retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440033",
      "user": {
        "id": "777e7777-e77b-77d7-a777-777777777777",
        "userName": "spam_account",
        "firstName": "Spam",
        "lastName": "Account",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/spam_account.jpg"],
        "isVerified": false
      },
      "createdAt": "2025-12-11T10:30:45"
    },
    {
      "id": "991e8400-e29b-41d4-a716-446655440044",
      "user": {
        "id": "999e9999-e99b-99d9-a999-999999999999",
        "userName": "troll_user",
        "firstName": "Troll",
        "lastName": "User",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/troll_user.jpg"],
        "isVerified": false
      },
      "createdAt": "2025-12-10T15:20:00"
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of blocked user objects, sorted by createdAt in descending order (newest first)
data[].id	Unique identifier for the block record (UUID format)
data[].user	Object containing information about the blocked user
data[].user.id	UUID of the blocked user
data[].user.userName	Username of the blocked user
data[].user.firstName	First name of the blocked user
data[].user.lastName	Last name of the blocked user
data[].user.profilePictureUrls	Array of profile picture URLs for the blocked user
data[].user.isVerified	Boolean indicating if the blocked account is verified
data[].createdAt	Timestamp when the block was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Unauthorized - Token Issues (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

6. Get Muted Users

Purpose: Retrieve the complete list of users muted by the authenticated user

Endpoint: GET {base_url}/e-social/privacy-control/muted

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Muted users retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440044",
      "user": {
        "id": "888e8888-e88b-88d8-a888-888888888888",
        "userName": "noisy_user",
        "firstName": "Noisy",
        "lastName": "User",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/noisy_user.jpg"],
        "isVerified": true
      },
      "createdAt": "2025-12-11T10:30:45"
    },
    {
      "id": "101e8400-e29b-41d4-a716-446655440055",
      "user": {
        "id": "100e1000-e10b-10d1-a100-100000000000",
        "userName": "oversharer",
        "firstName": "Over",
        "lastName": "Sharer",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/oversharer.jpg"],
        "isVerified": false
      },
      "createdAt": "2025-12-09T08:15:30"
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of muted user objects, sorted by createdAt in descending order (newest first)
data[].id	Unique identifier for the mute record (UUID format)
data[].user	Object containing information about the muted user
data[].user.id	UUID of the muted user
data[].user.userName	Username of the muted user
data[].user.firstName	First name of the muted user
data[].user.lastName	Last name of the muted user
data[].user.profilePictureUrls	Array of profile picture URLs for the muted user
data[].user.isVerified	Boolean indicating if the muted account is verified
data[].createdAt	Timestamp when the mute was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Unauthorized - Token Issues (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-12-11T10:30:45",
  "data": "Token has expired"
}

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/POST/DELETE request
400 Bad Request: Invalid request data or business rule violation
401 Unauthorized: Authentication required/failed
404 Not Found: Resource not found
500 Internal Server Error: Server error

Authentication

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-12-11T14:30:00Z)
IDs: UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)

Key Differences Between Block and Mute

Feature	Block	Mute
Removes follow relationships	Yes	No
Hides content	Yes	Yes
User knows they're blocked/muted	Possibly (can't follow)	No
Can send messages	No	Yes (if messaging exists)
Can view profile	Limited	Yes

User Relations Endpoints

Account Privacy APIs

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Get Privacy Settings

Application-Level Exceptions (400-499)

2. Update Privacy Settings

Application-Level Exceptions (400-499)

Quick Reference Guide

Common HTTP Status Codes

Authentication

Data Format Standards

Follow System APIs

How The Follow System Works

Relationship Context Logic

1. Your Own Followers List (/followers/{yourUserId})

2. Your Own Following List (/following/{yourUserId})

3. Friend's Followers List (/followers/{friendUserId})

4. Friend's Following List (/following/{friendUserId})

Privacy & Status Rules

UI Implementation Best Practices

Button State Management

Button Logic by Relationship State:

Why Single Button Design:

Confirmation Dialog Best Practices

Visual States & Feedback

Additional UI Elements

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Follow User

Application-Level Exceptions (400-499)

2. Unfollow User

Application-Level Exceptions (400-499)

3. Accept Follow Request

Application-Level Exceptions (400-499)

4. Decline Follow Request

Application-Level Exceptions (400-499)

5. Get Followers

Application-Level Exceptions (400-499)

6. Get Following

Application-Level Exceptions (400-499)

7. Get Followers (Paginated)

8. Get Following (Paginated)

9. Get Pending Follow Requests

10. Get User Stats

11. Check Follow Status

12. Get Featured Users

13. Get Featured Users (Paginated)

Quick Reference Guide

Common HTTP Status Codes

Authentication

Data Format Standards

Relationship Field Reference

Version History

Privacy Control API

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Block User

Application-Level Exceptions (400-499)

2. Unblock User

Application-Level Exceptions (400-499)

3. Mute User

Application-Level Exceptions (400-499)

4. Unmute User

Application-Level Exceptions (400-499)

5. Get Blocked Users

Application-Level Exceptions (400-499)

6. Get Muted Users

1. Your Own Followers List (`/followers/{yourUserId}`)

2. Your Own Following List (`/following/{yourUserId}`)

3. Friend's Followers List (`/followers/{friendUserId}`)

4. Friend's Following List (`/following/{friendUserId}`)