Follow System APIs

Follow System API Documentation

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

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).

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

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. 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"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier for the follow relationship (UUID format)
followerId	UUID of the user who initiated the follow request
followingId	UUID of the user who accepted the follow request
follower	Object containing summary information about the follower user
following	Object containing summary information about the user being followed
status	Follow status - now "ACCEPTED" after acceptance
createdAt	Timestamp when the original follow request was created (ISO 8601 format)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Follow request is not pending",
  "action_time": "2025-12-11T10:30:45",
  "data": "Follow request is not pending"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Follow request is not pending
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: Follow request not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Not Pending (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Follow request is not pending",
  "action_time": "2025-12-11T10:30:45",
  "data": "Follow request is not pending"
}

Not Found (404):

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

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
}

Success Response Fields:

Field	Description
data	Always null for this endpoint

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Follow request is not pending",
  "action_time": "2025-12-11T10:30:45",
  "data": "Follow request is not pending"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Follow request is not pending
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
404 NOT_FOUND: Follow request not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Not Pending (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Follow request is not pending",
  "action_time": "2025-12-11T10:30:45",
  "data": "Follow request is not pending"
}

Not Found (404):

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

5. Get Followers

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

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"
    },
    {
      "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"
    }
  ]
}

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)

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 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"
}

6. Get Following

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

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"
    }
  ]
}

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)

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 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"
}

7. Get Followers (Paginated)

Purpose: Retrieve a paginated list of users following a specified user

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"
      }
    ],
    "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
data.content[].id	Unique identifier for the follow relationship
data.content[].user	Object containing information about the follower user
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

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 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"
}

8. Get Following (Paginated)

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

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"
      }
    ],
    "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
data.content[].id	Unique identifier for the follow relationship
data.content[].user	Object containing information about the followed 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

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 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"
}

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"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440022",
      "user": {
        "id": "444e4444-e44b-44d4-a444-444444444444",
        "userName": "david_lee",
        "firstName": "David",
        "lastName": "Lee",
        "profilePictureUrls": ["https://cdn.nexgate.com/profiles/david_lee.jpg"],
        "isVerified": true
      },
      "status": "PENDING",
      "createdAt": "2025-12-11T08:00:00"
    }
  ]
}

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[].user.id	UUID of the requesting user
data[].user.userName	Username of the requesting user
data[].user.firstName	First name of the requesting user
data[].user.lastName	Last name of the requesting user
data[].user.profilePictureUrls	Array of profile picture URLs for the requesting user
data[].user.isVerified	Boolean indicating if the requesting account is verified
data[].status	Follow status - always "PENDING" for this endpoint
data[].createdAt	Timestamp when the follow request 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"
}

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

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 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"
}

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)

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 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"
}

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

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"
}

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

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)
Pagination: 1-indexed pages (page=1 for first page), default size=20

Account Privacy APIs

Follow System APIs

Privacy Control API

Follow System APIs

Follow System API Documentation

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)

Application-Level Exceptions (400-499)

8. Get Following (Paginated)

Application-Level Exceptions (400-499)

9. Get Pending Follow Requests

Application-Level Exceptions (400-499)

10. Get User Stats

Application-Level Exceptions (400-499)

11. Check Follow Status

Application-Level Exceptions (400-499)

12. Get Featured Users

Application-Level Exceptions (400-499)

13. Get Featured Users (Paginated)

Application-Level Exceptions (400-499)

Quick Reference Guide

Common HTTP Status Codes

Authentication

Data Format Standards