User Connections

The User Connections API allows users to build social connections with other players on your platform. Users can send connection requests, accept or decline incoming requests, and manage their network of connections.

Overview

User connections create a social layer that enhances the gaming experience by:

Building Communities: Players can connect with like-minded gamers
Enhanced Matchmaking: Connections can influence recommendation algorithms
Social Gaming: Connected users can coordinate gaming sessions
Trust Networks: Established connections build trust between players

Connection Workflow

Connection Request Flow

graph LR
    A[User A] -->|Sends Request| B[User B]
    B -->|Accepts| C[Connection Created]
    B -->|Declines| D[Request Declined]
    C --> E[Both Users Notified]
    D --> F[User A Notified]

Connection States

Pending: Request sent, waiting for response
Accepted: Request approved, users are connected
Declined: Request rejected, no connection created

API Usage

Send Connection Request

POST /v1/connections/{user_id}/request

Send a connection request to another user.

Request:

curl -X POST \
  "https://api.playsync.com/v1/connections/user123/request" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_id": "user456",
    "message": "Hi! I saw we both play FPS games. Want to connect?"
  }'

Response:

{
  "message": "Connection request sent successfully",
  "id": 123
}

Accept Connection Request

POST /v1/connections/{user_id}/accept/{request_id}

Accept a pending connection request from another user.

Request:

curl -X POST \
  "https://api.playsync.com/v1/connections/user456/accept/123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Connection request accepted successfully"
}

Decline Connection Request

POST /v1/connections/{user_id}/decline/{request_id}

Decline a pending connection request from another user.

Request:

curl -X POST \
  "https://api.playsync.com/v1/connections/user456/decline/123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Connection request declined successfully"
}

Get Sent Connection Requests

GET /v1/connections/{user_id}/sent

Get a paginated list of connection requests sent by the user.

Request:

curl -X GET \
  "https://api.playsync.com/v1/connections/user123/sent?page=1&per_page=10&status=pending" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "requests": [
    {
      "id": 123,
      "user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "status": "pending",
      "message": "Hi! I saw we both play FPS games. Want to connect?",
      "created_at": "2024-01-15T10:30:00Z",
      "responded_at": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_items": 25,
    "per_page": 10
  }
}

Get Received Connection Requests

GET /v1/connections/{user_id}/received

Get a paginated list of connection requests received by the user.

Request:

curl -X GET \
  "https://api.playsync.com/v1/connections/user456/received?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "requests": [
    {
      "id": 124,
      "user": {
        "client_user_id": "user789",
        "display_name": "PlayerThree"
      },
      "status": "pending",
      "message": "Let's connect!",
      "created_at": "2024-01-15T11:00:00Z",
      "responded_at": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "per_page": 10
  }
}

Get Active Connections

GET /v1/connections/{user_id}/active

Get a paginated list of active connections for the user.

Request:

curl -X GET \
  "https://api.playsync.com/v1/connections/user123/active?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "connections": [
    {
      "id": 456,
      "connected_user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "connected_since": "2024-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "per_page": 10
  }
}

Get Connection Notifications

GET /v1/connections/{user_id}/notifications

Get all notifications related to connection events for the user.

Request:

curl -X GET \
  "https://api.playsync.com/v1/connections/user123/notifications" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "notifications": [
    {
      "type": "new_request",
      "connection_request_id": 125,
      "other_user": {
        "client_user_id": "user101",
        "display_name": "PlayerFour"
      },
      "message": "Hi! I'd like to connect with you.",
      "timestamp": "2024-01-15T13:00:00Z",
      "read": false
    },
    {
      "type": "request_accepted",
      "connection_request_id": 123,
      "other_user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "message": "Your connection request was accepted!",
      "timestamp": "2024-01-15T12:00:00Z",
      "read": true
    }
  ],
  "unread_count": 1
}

Mark Notification as Read

POST /v1/connections/{user_id}/notifications/{notification_id}/read

Mark a specific connection notification as read.

Request:

curl -X POST \
  "https://api.playsync.com/v1/connections/user123/notifications/125/read" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Notification marked as read"
}

Remove Connection

DELETE /v1/connections/{user_id}/{connection_id}

Remove an active connection between users.

Request:

curl -X DELETE \
  "https://api.playsync.com/v1/connections/user123/456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Connection removed successfully"
}

Query Parameters

Pagination Parameters

page (integer, default: 1): Page number (1-based)
per_page (integer, default: 10, max: 50): Items per page

Status Filtering

status (string, optional): Filter by status
- pending: Only pending requests
- accepted: Only accepted requests
- declined: Only declined requests
- all: All requests (default)

Connection Status Values

Connection requests can have the following statuses:

pending: Request sent but not yet responded to
accepted: Request accepted, users are now connected
declined: Request declined, no connection created

Notification Types

Connection notifications include the following types:

new_request: A new connection request was received
request_accepted: A sent connection request was accepted
request_declined: A sent connection request was declined

Example: Complete Connection Flow

# 1. User A sends connection request to User B
curl -X POST "https://api.playsync.com/v1/connections/userA/request" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_id": "userB",
    "message": "Hi! Want to connect?"
  }'

# 2. User B checks received requests
curl -X GET "https://api.playsync.com/v1/connections/userB/received" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 3. User B accepts the request
curl -X POST "https://api.playsync.com/v1/connections/userB/accept/123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 4. Both users check their active connections
curl -X GET "https://api.playsync.com/v1/connections/userA/active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET "https://api.playsync.com/v1/connections/userB/active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Handling

Common error responses:

User not found:

{
  "error": "Resource not found",
  "message": "User with ID 'user123' does not exist"
}

Not authorized:

{
  "error": "Forbidden",
  "message": "Not authorized to accept this request"
}

Request already processed:

{
  "error": "Conflict",
  "message": "Request already processed"
}

Users already connected:

{
  "error": "Conflict",
  "message": "Users are already connected"
}

Best Practices

Handle Status Updates: Monitor connection request statuses and update your UI accordingly
Use Pagination: Implement pagination for large connection lists
Real-time Updates: Poll for notifications or implement WebSocket connections for live updates
Error Handling: Implement proper error handling for all connection operations
User Privacy: Respect user preferences for receiving connection requests

Integration Tips

Recommendations: Use connections to improve your recommendation algorithms
Matchmaking: Integrate connections with your gaming session matchmaking
Social Features: Build community features around user connections
Analytics: Track connection patterns to understand user engagement

Overview​

Connection Workflow​

Connection Request Flow​

Connection States​

API Usage​

Send Connection Request​

Accept Connection Request​

Decline Connection Request​

Get Sent Connection Requests​

Get Received Connection Requests​

Get Active Connections​

Get Connection Notifications​

Mark Notification as Read​

Remove Connection​

Query Parameters​

Pagination Parameters​

Status Filtering​

Connection Status Values​

Notification Types​

Example: Complete Connection Flow​

Error Handling​

Best Practices​

Integration Tips​

Overview

Connection Workflow

Connection Request Flow

Connection States

API Usage

Send Connection Request

Accept Connection Request

Decline Connection Request

Get Sent Connection Requests

Get Received Connection Requests

Get Active Connections

Get Connection Notifications

Mark Notification as Read

Remove Connection

Query Parameters

Pagination Parameters

Status Filtering

Connection Status Values

Notification Types

Example: Complete Connection Flow

Error Handling

Best Practices

Integration Tips