REST: Social Graph

This page documents the social-graph REST surface in BuddyNext free: following, connections (mutual/two-way relationships), and the block/mute/restrict privacy controls. All routes live under the buddynext/v1 namespace and are registered by FollowController, ConnectionController, and BlockController in includes/SocialGraph/.

Overview / Contract

• Base namespace: buddynext/v1. Full base URL: /wp-json/buddynext/v1.
• Authentication is cookie + nonce (X-WP-Nonce) for first-party requests, or any standard WordPress REST auth (Application Passwords, etc.). Routes marked Public use __return_true and need no auth. Routes marked Auth require a logged-in user (require_auth).
• All write routes apply a capability gate in addition to the auth check: follow/unfollow gate on buddynext-connections/follow, connect/withdraw gate on buddynext-connections/connect. A user whose role is denied the capability gets a 403 even when logged in.
• Block state is enforced on relationship writes: following or connecting with a user who blocks (or is blocked by) you returns 403 buddynext_blocked.
• Targeting a non-existent user id returns 404 buddynext_user_not_found.
• List routes take per_page; /users/{id}/followers, /users/{id}/following, and /me/connections are keyset-paginated - pass cursor from the previous response's next_cursor - while /me/connection-requests still uses page.

See the REST contract page (14-rest-contract) for the shared envelope, pagination headers, error shape, and nonce handling that apply to every route below.

Follow routes

Follow is a one-directional relationship. When the target account is private (account type gated), a follow becomes a pending follow-request the target approves or rejects.

Connection routes

A connection is a mutual, two-sided relationship (request, then accept). An optional note (capped at 280 characters, tags stripped) can accompany the request.

Note: Connection requests are approved or declined through the per-peer /users/{id}/connect/accept and /users/{id}/connect/decline routes. There are no separate /me/connection-requests/{id}/approve|reject endpoints; the peer id in the connect path is the actor on the other side of the request.

Block, mute, and restrict routes

These are the per-user privacy controls. Block is mutual-cut (neither party sees the other), mute hides someone's content from you only, and restrict limits their interaction with you. Each control has a POST (apply) and DELETE (remove) on the same path, plus a list route.

Examples

Follow a user

curl -X POST "https://example.com/wp-json/buddynext/v1/users/42/follow" \
  -H "X-WP-Nonce: <wp_rest_nonce>" \
  --cookie "<auth cookies>"

Response when the target is a public account (followed immediately):

{
  "following": true,
  "pending": false
}

Response when the target is private (a pending follow-request was created):

{
  "following": false,
  "pending": true
}

A blocked relationship returns:

{
  "code": "buddynext_blocked",
  "message": "You cannot follow this user.",
  "data": { "status": 403 }
}

Send a connection request

curl -X POST "https://example.com/wp-json/buddynext/v1/users/42/connect" \
  -H "X-WP-Nonce: <wp_rest_nonce>" \
  -H "Content-Type: application/json" \
  --cookie "<auth cookies>" \
  -d '{ "note": "We met at the community meetup - would like to connect." }'

Response:

{
  "status": "pending"
}

The recipient then accepts with POST /users/{your_id}/connect/accept or declines with POST /users/{your_id}/connect/decline.

Notes / gotchas

• Capability gates are symmetric. Unfollow is gated on the same follow capability as follow, and withdraw on the same connect capability as connect, so a role denied the action cannot mutate state in either direction.
• Block precedence. is_blocking_either() is checked before any follow or connect write; a block by either party short-circuits the relationship with 403 buddynext_blocked.
• Public vs Auth listing. Follower/following lists and follow-suggestions reflect public-graph reads; /users/{id}/followers and /users/{id}/following are public, while /follow-suggestions is per-user and requires auth.
• Account type drives the UI flow. Read /users/{id}/account-type (or the pending flag in the follow response) to decide whether to show "Follow" or "Request to follow".
• Pagination. The followers, following, and /me/connections routes are keyset-paginated: pass cursor (from the prior response's next_cursor) and per_page, and read next_cursor and total from the response. /me/connection-requests still uses page (default 1) and per_page (default 20). Do not assume the full set in one call.