Comstack Friends API

Hi!

This document follows on from the Comstack Private Messaging REST API documentation, same thinking rules etc applies.

With that in mind this document will only cover the endpoints and data models, if you want to know how paging, filtering, sorting and what else is available to you, refer to the Comstack Private Messaging REST API documentation.

Base path

The API will live at /api/v1/cs-fr on the installed site.

Examples

See the end of this document.

Endpoints

/friends

GET /api/v1/cs-fr/friends Show details

List the current users friends. This will include pending friend requests which are noted by the approved property.

Requires: Authenticated user session.

Default limit: 50.

Responses

Status Description Example
200 Valid response.
Body
{
  "data": [
    {
      "type": "relationship",
      "id": 1,
      "relationship_type": "comstack_friends",
      "user": {
        "type": "user",
        "id": 1,
        "name": "username"
        "avatars": {
          "100-100": "https://example.com/sites/default/files/styles/cs-100-100/public/avatars/av1.jpg?itok=123",
          "200-200": "https://example.com/sites/default/files/styles/cs-200-200/public/avatars/av1.jpg?itok=123"
        },
        "contact_frequency": 0
      },
      "created": "2015-08-03T16:34:58+01:00",
      "changed": "2015-08-03T16:35:55+01:00",
      "approved": true
    },
    ...
  ],
  "paging": {
    // See the Comstack Private Messaging documentation for that.
  }
}
204 No content (you don't have any friends :C).
POST /api/v1/cs-fr/friends Show details

Send/create a new friend request.

Request body

Property Type Description Required?
user Integer The ID of the user you'd like to be friends with.

Example request body

{
  "user": 2
}

Responses

Status Description Example
201 Request sent.
Headers
Body
{
  // See relationship model.
}
400 Validation issue, in this case you've not sent a valid ID number.

/friends/{relationship_id}

GET /api/v1/cs-fr/friends/{relationship_id} Show details

Get a specific relationship.

Requires: Authenticated user session.

Responses

Status Description Example
200 Relationship found.
Body
{
  // See relationship model.
}
404 Relationship not found.
DELETE /api/v1/cs-fr/friends/{relationship_id} Show details

Delete a friend relationship.

Responses

Status Description Example
200 The relationship has been deleted.
400 Failed to delete relationship.
404 Relationship not found.

/friends/{relationship_id}/approve

PUT /api/v1/cs-fr/friends/{relationship_id}/approve Show details

Approve a pending friend request.

Requires: Authenticated user session.

Responses

Status Description Example
200 The relationship has been approved.
400 Failed to approve relationship.
404 Relationship not found.

/friends/{relationship_id}/reject

PUT /api/v1/cs-fr/friends/{relationship_id}/reject Show details

Reject a friend request.

Requires: Authenticated user session.

Responses

Status Description Example
200 The friend request has been rejected.
400 Failed to reject the request.
404 Request not found.

/friends/{relationship_id}/cancel

PUT /api/v1/cs-fr/friends/{relationship_id}/cancel Show details

Cancel a friend request.

Requires: Authenticated user session.

Responses

Status Description Example
200 A friend request has been cancelled.
204 No content (no messages in conversation).
404 Conversation not found.

/blocked

GET /api/v1/cs-fr/blocked Show details

List the users that the current user has blocked.

Requires: Authenticated user session.

Default limit: 50.

Responses

Status Description Example
200 Valid response.
Body
{
  "data": [
    {
      "type": "relationship",
      "id": 2,
      "relationship_type": "comstack_blocked",
      "user": {
        "type": "user",
        "id": 3,
        "name": "username"
        "avatars": {
          "100-100": "https://example.com/sites/default/files/styles/cs-100-100/public/avatars/av1.jpg?itok=123",
          "200-200": "https://example.com/sites/default/files/styles/cs-200-200/public/avatars/av1.jpg?itok=123"
        },
        "contact_frequency": 0
      },
      "created": "2015-08-03T16:34:58+01:00",
      "changed": "2015-08-03T16:35:55+01:00",
    },
    ...
  ],
  "paging": {
    // See the Comstack Private Messaging documentation for that.
  }
}
204 No content (you've not blocked anyone).
POST /api/v1/cs-fr/blocked Show details

Create a new blocked relationship, block someone.

Request body

Property Type Description Required?
user Integer The ID of the user you'd like to block.

Example request body

{
  "user": 3
}

Responses

Status Description Example
201 Request sent.
Body
{
  // See relationship model.
}
400 Validation issue, in this case you've not sent a valid ID number.

/blocked/{relationship_id}

GET /api/v1/cs-fr/blocked/{relationship_id} Show details

Get a specific blocked relationship.

Requires: Authenticated user session.

Responses

Status Description Example
200 Relationship found.
Body
{
  // See relationship model.
}
404 Relationship not found.
DELETE /api/v1/cs-fr/blocked/{relationship_id} Show details

Delete a blocked relationship, unblock someone.

Responses

Status Description Example
200 The relationship has been deleted.
400 Failed to delete relationship.
404 Relationship not found.

Models

Relationship Show details

Structure
Property Type Description
type String The type of entity that this is for convenience, relationship.
id Integer ID of the relationship record.
user Object The user that this relationship is with.
created String An ISO 8601 date and time including timezone of when the relationship was started or requested.
changed String An ISO 8601 date and time including timezone of when the relationship was last updated.
approved Boolean Whether or not the relationship has been approved, for friends if false then the request is pending. Blocked relationships are one sided so always approved.
Example
{
  "type": "relationship",
  "id": 1,
  "relationship_type": "comstack_friends",
  "user": {
    "type": "user",
    "id": 1,
    "name": "username"
    "avatars": {
      "100-100": "https://example.com/sites/default/files/styles/cs-100-100/public/avatars/av1.jpg?itok=123",
      "200-200": "https://example.com/sites/default/files/styles/cs-200-200/public/avatars/av1.jpg?itok=123"
    },
    "contact_frequency": 0
  },
  "created": "2015-08-03T16:34:58+01:00",
  "changed": "2015-08-03T16:35:55+01:00",
  "approved": true
}

Examples

Get me a list of my friends:

GET /api/v1/cs-fr/friends?filter[approved]=1

Get me a list of pending friend requests for me to approve or reject:

GET /api/v1/cs-fr/friends?filter[approved]=0

Check to see if I'm friends with someone, where their user ID is 9:

GET /api/v1/cs-fr/friends?filter[user]=9