General concept

We have a simplier way of retrieving user’s friends list, so visit Friends API page if you only need that functionality.

Y8 uses a follower system (similar to Twitter, for example). A user can follow another user and remain notified about his activities, until another user blocks him.

When the user starts following someone else, link between them is created. Link has four possible states:

  • Pending (state from which all contacts start)
  • Accepted (means that receiver reviewed link)
  • Blocked (user forbids following him)
  • Mutual (users accepts following and follows back)

Listing actions

Y8 presents a list of consistent interfaces to view and manage user affiliations.

Methods, listed above only affect users that are already registered in your application. Effectively, this means that if user Jacob has friends Mason and Ethan, Mason has logged into your application and Ethan has not, you will only get Mason when retrieving Jacob’s friend list.

Getting friends list

Request

GET: "https://account.y8.com/api/v1/json/links/friends"

Will result in list of users that current user follows and that followed him back.

Response

{
  "results": [
    {
      "pid": "0000000001",
      "nickname": "Nettor",
      "first_name": "Mason",
      "last_name": "Johnson",
      "date_of_birth": "1990-03-05"
    },
    {
      "pid": "0000000042",
      "nickname": "L337_n00b",
      "first_name": null,
      "last_name": null,
      "date_of_birth": null
    }
  ]
}

Getting followees list

Request

GET: "https://account.y8.com/api/v1/json/links/followees"

Will result in list of users that current user follows.

Response

See friends response

Getting followers list

Response

GET: "https://account.y8.com/api/v1/json/links/followees"

Will result in list of users that follow current user.

This list won't include user's friends

There is another way to get incoming connections:

GET: "https://account.y8.com/api/v1/json/links/pending"

This differs from previous one, because it excludes accepted requests. So, effectively, it is a subset of followers. This request could be used for getting new follow requests, not reviewed by user.

Response

See friends response

Getting blocked users list

Request

GET: "https://account.y8.com/api/v1/json/links/blocked"

Will result in list of users that are blocked by the current user.

This list won't include user's friends

Response

See friends response

Managing contacts

Here is comprehensive list of how to manipulate user contacts with the API:

Follow request

POST: "https://account.y8.com/api/v1/json/links/follow/[target-pid]"

After this action target will appear in followees list.

Server will return 409 error if follow request is already sent.

Response

{
  "from": "0000000002", #current_user_pid
  "to": "000000000001", #receiver_pid
  "status": "ok",
  "method": "follow"
}

Unfollow request

POST: "https://account.y8.com/api/v1/json/links/unfollow/[target-pid]"

Response

See follow response. Only method (unfollow) differs.

Reviewing incoming request

Accept

POST: "https://account.y8.com/api/v1/json/links/accept/[target-pid]"

Marks request ‘as read’, so it won’t appear in the pending contacts list.

Response

See follow response. Only method (accept) differs.

Add to friends

POST: "https://account.y8.com/api/v1/json/links/mutual_accept/[target-pid]"

Will add target to the current accounts friends. Same will happen if both target and current user will create follow requests.

Response

See follow response. Only method (mutual_accept) differs.

Blocking users

Block request

POST: "https://account.y8.com/api/v1/json/links/block/[target-pid]"

Will forbid target user from following current user and will add him to the blocked list.

Response

See follow response. Only method (block) differs.

Unblock

Block can be lifted by using following request:

POST: "https://account.y8.com/api/v1/json/links/unblock/[target-pid]"

After it target will no longer be banned, link will get accepted state and target will appear in followers list.

Response

See follow response. Only method (unblock) differs.

Check

Check if another pid is a friend

POST: "https://account.y8.com/api/v1/json/links/check"
Data: {pids: ['55a7e84be13823367e00000e']}

Response

{"55a7e84be13823367e00000e": true}