Identities endpoints

Following a User

For purposes of this discussion:

  • Your User: Refers to the user currently authenticated via your Session Token
  • Followed Users: Refers to users “followed” by Your User as defined below.

Define Following

A User is Followed if:

  • Your User has ever been in a Conversation with the other user
  • Your User has explicitly followed the other user (or a request sent on their behalf of Your User to follow the other user is sent via Client API or Server API)
  • Your User has not explicitly unfollowed the other user (or a request sent on their behalf using Client API or Server API)

A Followed User has the following behaviors from the perspective of Your User:

  • The Followed User is returned in any request listing users followed by Your User
  • WebSocket Change Events will be delivered to Your User for any changes to Identity objects for any Followed Users

Rationale

There are a few goals served by Following a user:

  1. Improved Rendering: While many applications will just use the display_name and avatar_url that comes with each Message to display the sender of the Message, some applications may need additional information when rendering users. To accomplish this, and to minimize the amount of on-demand fetching of users, your application can load the full Identity objects for all of the user’s the current user is following.
  2. On having a cache of user data, that cache needs to be maintained in the event of any changes (i.e. a user changes their Avatar)
  3. For applications that don’t already maintain a list of users your user can talk to, there are advantages to using this existing cache of data to drive any user lists. Useful for example when selecting users to create a Conversation with or add a user to an existing Conversation.
  4. Using information outside of display_name for rendering the user in a User List or next to their Messages. For example, there may be information in the Identity metadata property that affects how they are rendered (blue for admin, red for novice users, etc…)

Endpoint Details

Method HTTP request Description
Get Followed Identities GET /identities Get Followed Identity objects
Get Followed Users GET /following Get Followed User IDs
Get an Identity GET /identities/:user_id Returns a single Identity object
Is User Followed GET /following/users/:user_id Test if the user is followed
Follow a User PUT /following/users/:user_id Add this user_id to the list of Followed Users
Follow Multiple Users POST /following/users Add the specified User IDs to the list of Followed Users
Unfollow a User DELETE /following/users/:user_id Remove this user from the list of Followed Users

Get Followed Identities

Get an array of Followed Identity objects.

Parameters:

Name Type Description
page_size integer (optional) Number of results to return; 500 is default
from_id string (optional) Get the Identities after this ID. Can be passed as a Layer URI layer:///identities/userId or simply a user_id

HTTP request:

GET/identities

Example:

"page_size=500&from_id=1234"
curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/identities?page_size=500&from_id=1234

Possible responses:

Request successful | Status: 200 (OK)

[
    Identity,
    Identity
]

Get Followed Users

Get an array of Followed User IDs.

Parameters:

Name Type Description
page_size integer (optional) undefined
from_id string (optional) Get the User IDs logically sorted after this ID. Can be passed as a Layer URI layer:///identities/userId or simply a user_id

HTTP request:

GET/following

Example:

"page_size=500&from_id=1234"
curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/following?page_size=500&from_id=1234

Possible responses:

Request successful | Status: 200 (OK)

[
    "1234",
    "777",
    "999"
]

Get an Identity

Returns an Identity object of a single user of this app.

Parameters:

This method takes no parameters.

HTTP request:

GET/identities/:user_id

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/identities/<user_id>

Possible responses:

Request successful | Status: 200 (OK)

Identity

Is User Followed

Returns a 204 or 404 to indicate if the user is followed or not.

Parameters:

This method takes no parameters.

HTTP request:

GET/following/users/:user_id

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/following/users/<user_id>

Possible responses:

User is Followed
Status: 204 (No Content)
(Empty body)

User is not Followed | Status: 404 (Not Found)

{
    "id": "not_found",
    "code": 102,
    "message": "A user identity with the specified identifier could not be found.",
    "url": "https://developer.layer.com/docs/client/rest#not_found"
}

The user_id was not found in the list of users followed by your user

Follow a User

Parameters:

This method takes no parameters.

HTTP request:

PUT/following/users/:user_id

Example:

curl -X PUT \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/following/users/<user_id>

Possible responses:

Participant followed successfully
Status: 204 (No Content)
(Empty body)

Follow Multiple Users

Parameters:

Name Type Description
data string[] Array of User IDs

HTTP request:

POST/following/users

Example:

[
    "1234",
    "777",
    "999"
]
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/following/users\
 -d '["1234","777","999"]'

Possible responses:

Request Accepted
Status: 202 (Accepted)
(Empty body)

Unfollow a User

A user can be removed from the list of Followed Users. Note that after unfollowing a user they may be implicitly refollowed if they join another Conversation together.

Parameters:

This method takes no parameters.

HTTP request:

DELETE/following/users/:user_id

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/following/users/<user_id>

Possible responses:

User Unfollowed
Status: 204 (No Content)
(Empty body)