Relationships Feature

The Relationships feature manages social connections between users, including friendships, following relationships, and user interactions.

Overview

Relationships enable users to:

Send and accept friend requests
Follow other users
View friends and followers lists
Get friend suggestions
Block and unblock users
Track mutual connections
Manage relationship status

Friendship System

Send Friend Request

Send a friend request to another user:

POST /api/friendship/send-request
Authorization: Bearer {token}
Content-Type: application/json

{
  "toUserId": "user-guid-here",
  "message": "Hi! Let's connect!"  // Optional, max 500 chars
}

Response:

{
  "success": true,
  "message": "Friend request sent successfully",
  "data": {
    "id": 123,
    "fromUserId": "current-user-guid",
    "toUserId": "user-guid-here",
    "status": "Pending",
    "createdAt": "2024-01-15T10:00:00Z",
    "message": "Hi! Let's connect!",
    "version": 1
  }
}

Accept Friend Request

Accept a pending friend request:

POST /api/friendship/accept-request
Authorization: Bearer {token}
Content-Type: application/json

{
  "friendshipId": 123
}

Response:

{
  "success": true,
  "message": "Friend request accepted successfully",
  "data": {
    "id": 123,
    "fromUserId": "user-guid-here",
    "toUserId": "current-user-guid",
    "status": "Accepted",
    "createdAt": "2024-01-15T10:00:00Z",
    "acceptedAt": "2024-01-15T11:00:00Z",
    "message": "Hi! Let's connect!",
    "version": 2
  }
}

Decline Friend Request

Decline a pending friend request:

POST /api/friendship/decline-request
Authorization: Bearer {token}
Content-Type: application/json

{
  "friendshipId": 123
}

Response:

{
  "success": true,
  "message": "Friend request declined successfully",
  "data": {
    "id": 123,
    "status": "Declined",
    "declinedAt": "2024-01-15T11:00:00Z"
  }
}

Unfriend

Remove a friendship:

POST /api/friendship/unfriend
Authorization: Bearer {token}
Content-Type: application/json

{
  "userId2": "user-guid-here"
}

Response:

{
  "success": true,
  "message": "Unfriended successfully",
  "data": true
}

Viewing Friends

Get Friends List

Retrieve your friends list with pagination:

GET /api/friendship/friends?page=1&pageSize=20
Authorization: Bearer {token}

Query Parameters:

page (optional) - Page number (default: 1)
pageSize (optional) - Items per page (default: 20)

Response:

{
  "success": true,
  "message": "Friends retrieved successfully",
  "data": {
    "items": [
      {
        "id": "user-guid",
        "userName": "johndoe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "avatarUrl": "https://...",
        "createdAt": "2024-01-01T00:00:00Z",
        "lastActiveAt": "2024-01-15T10:00:00Z",
        "isActive": true,
        "location": "New York, USA",
        "interests": ["photography", "travel"],
        "tags": ["photographer", "traveler"]
      }
    ],
    "totalCount": 150,
    "page": 1,
    "pageSize": 20,
    "totalPages": 8
  }
}

Get Pending Friend Requests

Get pending friend requests (sent and received):

GET /api/friendship/pending-requests?page=1&pageSize=20
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Pending requests retrieved successfully",
  "data": {
    "sent": [
      {
        "id": 123,
        "toUserId": "user-guid",
        "toUserName": "janedoe",
        "toUserAvatar": "https://...",
        "status": "Pending",
        "createdAt": "2024-01-15T10:00:00Z",
        "message": "Hi! Let's connect!"
      }
    ],
    "received": [
      {
        "id": 124,
        "fromUserId": "user-guid",
        "fromUserName": "bobsmith",
        "fromUserAvatar": "https://...",
        "status": "Pending",
        "createdAt": "2024-01-15T09:00:00Z",
        "message": "We should connect!"
      }
    ]
  }
}

Get Mutual Friends

Find mutual friends between you and another user:

GET /api/friendship/mutual-friends?userId2={user-guid}&limit=10
Authorization: Bearer {token}

Query Parameters:

userId2 (required) - The other user's ID
limit (optional) - Maximum results (default: 10)
page (optional) - Page number
pageSize (optional) - Items per page

Response:

{
  "success": true,
  "message": "Mutual friends retrieved successfully",
  "data": [
    {
      "id": "user-guid",
      "userName": "alice",
      "firstName": "Alice",
      "lastName": "Johnson",
      "avatarUrl": "https://...",
      "mutualFriendsCount": 5
    }
  ],
  "totalCount": 10
}

Get Friend Suggestions

Get personalized friend suggestions:

GET /api/friendship/suggestions?limit=20
Authorization: Bearer {token}

Query Parameters:

limit (optional) - Maximum suggestions (default: 20)

Response:

{
  "success": true,
  "message": "Friend suggestions retrieved successfully",
  "data": [
    {
      "id": 123,
      "userId": "current-user-guid",
      "suggestedUserId": "user-guid",
      "suggestedUser": {
        "id": "user-guid",
        "userName": "johndoe",
        "firstName": "John",
        "lastName": "Doe",
        "avatarUrl": "https://..."
      },
      "score": 0.85,
      "reasons": [
        "Mutual friends: 5",
        "Same location: New York",
        "Similar interests: photography, travel"
      ],
      "createdAt": "2024-01-15T10:00:00Z",
      "isDismissed": false
    }
  ]
}

Suggestion Reasons:

Mutual friends count
Same location
Similar interests
Common connections
Activity patterns

Get Relationship Status

Check the relationship status between you and another user:

GET /api/friendship/relationship-status?userId2={user-guid}
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Relationship status retrieved successfully",
  "data": {
    "status": "Accepted",  // "Accepted", "Pending", "Declined", "Blocked", "None"
    "areFriends": true,
    "isBlocked": false,
    "isPending": false,
    "isDeclined": false,
    "friendshipId": 123,
    "createdAt": "2024-01-01T00:00:00Z",
    "acceptedAt": "2024-01-01T01:00:00Z"
  }
}

Follow System

Follow User

Follow another user to see their public posts:

POST /api/follow/follow
Authorization: Bearer {token}
Content-Type: application/json

{
  "followingId": "user-guid-here"
}

Response:

{
  "success": true,
  "message": "User followed successfully",
  "data": {
    "id": 123,
    "followerId": "current-user-guid",
    "followingId": "user-guid-here",
    "createdAt": "2024-01-15T10:00:00Z",
    "isActive": true,
    "version": 1
  }
}

Unfollow User

Unfollow a user:

POST /api/follow/unfollow
Authorization: Bearer {token}
Content-Type: application/json

{
  "followingId": "user-guid-here"
}

Response:

{
  "success": true,
  "message": "User unfollowed successfully",
  "data": true
}

Get Followers

Get list of users following you:

GET /api/follow/followers?userId={user-guid}&page=1&pageSize=20
Authorization: Bearer {token}

Query Parameters:

userId (required) - User ID
page (optional) - Page number (default: 1)
pageSize (optional) - Items per page (default: 20)

Response:

{
  "success": true,
  "message": "Followers retrieved successfully",
  "data": {
    "items": [
      {
        "id": "user-guid",
        "userName": "johndoe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "avatarUrl": "https://...",
        "createdAt": "2024-01-01T00:00:00Z",
        "lastActiveAt": "2024-01-15T10:00:00Z",
        "isActive": true,
        "location": "New York, USA",
        "interests": ["photography"],
        "tags": ["photographer"]
      }
    ],
    "totalCount": 150,
    "page": 1,
    "pageSize": 20,
    "totalPages": 8
  }
}

Get Following

Get list of users you are following:

GET /api/follow/following?userId={user-guid}&page=1&pageSize=20
Authorization: Bearer {token}

Response: Same format as followers list

Get Follow Statistics

Get follow statistics for a user:

GET /api/follow/stats?userId={user-guid}
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Follow statistics retrieved successfully",
  "data": {
    "followerCount": 150,
    "followingCount": 75,
    "isFollowing": true,      // Current user is following this user
    "isFollowedBy": false     // This user is following current user
  }
}

Get Mutual Followers

Find mutual followers between you and another user:

GET /api/follow/mutual-followers?userId2={user-guid}&limit=10
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Mutual followers retrieved successfully",
  "data": [
    {
      "id": "user-guid",
      "userName": "alice",
      "firstName": "Alice",
      "lastName": "Johnson",
      "avatarUrl": "https://..."
    }
  ]
}

Blocking Users

Block User

Block a user to prevent them from interacting with you:

POST /api/friendship/block
Authorization: Bearer {token}
Content-Type: application/json

{
  "toUserId": "user-guid-here"
}

What happens when you block someone:

They cannot send you friend requests
They cannot see your posts (even public ones)
They cannot message you
They cannot see you in search results
Any existing friendship is automatically removed

Response:

{
  "success": true,
  "message": "User blocked successfully",
  "data": {
    "id": 123,
    "status": "Blocked",
    "blockedAt": "2024-01-15T10:00:00Z"
  }
}

Unblock User

Unblock a previously blocked user:

POST /api/friendship/unblock
Authorization: Bearer {token}
Content-Type: application/json

{
  "toUserId": "user-guid-here"
}

Response:

{
  "success": true,
  "message": "User unblocked successfully",
  "data": {
    "id": 123,
    "status": "Accepted",
    "blockedAt": null
  }
}

Relationship Statuses

Friendship Status

Status	Description
Pending	Friend request sent, waiting for response
Accepted	Friend request accepted, users are friends
Declined	Friend request declined
Blocked	User is blocked

Follow Status

Active: Following relationship is active
Inactive: Following relationship was removed

Friend Suggestions Algorithm

Friend suggestions are based on:

Mutual Friends (40%)
- Number of common friends
- Strength of mutual connections
Location (20%)
- Same city or region
- Proximity-based suggestions
Interests (20%)
- Common interests and hobbies
- Similar activity patterns
Connections (15%)
- People who follow similar users
- Network overlap
Activity (5%)
- Similar posting patterns
- Engagement with similar content

Best Practices

Managing Friendships

Personalize Requests: Add a message when sending friend requests
Respond Promptly: Accept or decline requests in a timely manner
Review Suggestions: Regularly check friend suggestions to expand your network
Respect Privacy: Don't send multiple requests to the same user
Use Blocking Wisely: Only block users when necessary for your safety

Following vs. Friends

Friends: Mutual relationship, both users must accept
Following: One-way relationship, no acceptance needed
Use Cases:
- Follow: Public figures, brands, content creators
- Friends: Personal connections, close relationships

Privacy Considerations

Friend requests are private (only visible to involved users)
Friend lists can be configured in privacy settings
Blocked users cannot see your profile or content
Mutual friends are visible to both users

API Reference

Relationship endpoints: api/Friendship (send-request, accept, decline, block, unblock, unfriend, friends, pending-requests, mutual-friends, suggestions, relationship-status, blocked-users) and api/Follow. See the API Intro route table and Users API.

Notifications Feature - Friend request notifications
Posts Feature - See friends' posts in feed
Messaging Feature - Message your friends
User Management - Profile and privacy settings

Overview​

Friendship System​

Send Friend Request​

Accept Friend Request​

Decline Friend Request​

Unfriend​

Viewing Friends​

Get Friends List​

Get Pending Friend Requests​

Get Mutual Friends​

Get Friend Suggestions​

Get Relationship Status​

Follow System​

Follow User​

Unfollow User​

Get Followers​

Get Following​

Get Follow Statistics​

Get Mutual Followers​

Blocking Users​

Block User​

Unblock User​

Relationship Statuses​

Friendship Status​

Follow Status​

Friend Suggestions Algorithm​

Best Practices​

Managing Friendships​

Following vs. Friends​

Privacy Considerations​

API Reference​

Related Features​

Overview

Friendship System

Send Friend Request

Accept Friend Request

Decline Friend Request

Unfriend

Viewing Friends

Get Friends List

Get Pending Friend Requests

Get Mutual Friends

Get Friend Suggestions

Get Relationship Status

Follow System

Follow User

Unfollow User

Get Followers

Get Following

Get Follow Statistics

Get Mutual Followers

Blocking Users

Block User

Unblock User

Relationship Statuses

Friendship Status

Follow Status

Friend Suggestions Algorithm

Best Practices

Managing Friendships

Following vs. Friends

Privacy Considerations

API Reference

Related Features