Hi! Here's some basic stuff

The purpose of this document is to lay out clearly how the Comstack Private Messaging API can be interacted with so resources can be consumed, created and deleted.

Anywhere you see the term "RESTful" take that with a pinch of salt as in truth this API isn't restful, more is than not but certain things are present to make this API easier to work with.

I've flat out copied things I like from the following sources:

• https://github.com/WhiteHouse/api-standards
• https://github.com/RESTful-Drupal/restful/blob/7.x-1.x/docs/api_url.md
• https://www.hipchat.com/docs/apiv2

Assumptions

• Users will always be authenticated when accessing the API as if not there wouldn't be much point... Any non authenticated requests should be rejected with a 401 response.
• All responses will be application/json.
• You understand JSON, if not you can read up here: https://www.json.com

Guidelines

• A URL identifies a resource.
• URLs should include nouns, not verbs.
• Use plural nouns only for consistency (no singular nouns).
• You shouldn't need to go deeper than resource/identifier/resource.
• Put the version number at the base of your URL, for example http://example.com/v1/path/to/resource.
• URL v. header:
  • If it changes the logic you write to handle the response, put it in the URL.
  • If it doesn’t change the logic for each response, like OAuth info, put it in the header.
• Specify optional fields in a comma separated list.

Base path

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

HTTP Methods

Use HTTP verbs to operate on the collections and elements.

GET - Used to access data, this API will not allow modification to happen over GET.
POST - Create a resource.
PUT - Perform an action on a resource.
PATCH - Partially update a resource.
DELETE - Delete resources or undo an action.

Error Handling

If an error occurs when operating the REST endpoint via URL, A valid JSON object with code, message and description would be returned.

Here's an example...

{
  "status": 400,
  "title": "The sort wrong_key is not allowed for this path.",
  "detail": Bad Request.',
  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}

Response codes

When returning a response a HTTP code will always be used (duh). These have been clubbed together from various sources.

• https://docs.atlassian.com/atlassian-confluence/REST/latest
• https://dev.twitter.com/overview/api/response-codes

Rate limiting

Rate limiting won't be considered for this API at this time but should be thought of at some point to prevent abuse. As this API requires authentication this mitigates things in a minor way.

Result sets

Providing a response provides a body, list sets are always returned with a data property. Data items will always have type and id properties.

Along with a data property there will also be count and if enough results paging.

Filtering result sets

You can filter a result set on an endpoint by a property that belongs to the model being listed.

This follows the same format as laid out by the RESTful Drupal module.

Examples

Reducing a result set by a single field, in this case where the user models property name has the value alli.

/api/v1/cs-pm/users/available-users?filter[name]=alli

Reducing a result set by a field and specifying the operator.

Valid operators are "=", <, >, "<=", ">=", "<>", "!=", BETWEEN, CONTAINS (default), IN, LIKE, NOT IN, STARTS_WITH. Yes, the text is uppercase shouty, note that certain operators are wrapped in quote marks.

/api/v1/cs-pm/users/available-users?filter[name][value]=a&filter[name][operator]=STARTS_WITH

You can do multiple fields, multiple filters on a single field, lots!

Sorting result sets

As with filtering you can also sort on any data model property, do this by adding sort to the request query string.

The default direction for a sort is Ascending, if you prepend the property name with a minus - it will change the sort to Descending.

Example time!

/api/v1/cs-pm/users/available-users?sort=id

/api/v1/cs-pm/users/available-users?sort=-id

You can sort on multiple fields by separating things with a comma in the single sort query string parameter. Unlike with filtering you only ever set one sort param.

/api/v1/cs-pm/users/available-users?sort=id,name

/api/v1/cs-pm/users/available-users?sort=-contact_frequency,name

Only requesting certain properties

If for whatever reason you want to grab some data, and only have it return certain fields, for example "Give me all the users the current user can contact, but only give me their ID and name (username)".

You would do this by adding fields to the query string. Specify multiple fields by separating them with a comma.

/api/v1/cs-pm/users/available-users?fields=id

/api/v1/cs-pm/users/available-users?fields=id,name

Paging result sets

All Comstack endpoints will provide paging information of some kind within the paging root property of the response, next to data.

The information included will be a previous and/or next page if there is one, a total count of data found (e.g. 99) and the range of the data returned which is basically number per page.

Here's an example of the standard "Offset pagination" which means normal, pages 1, 2, 3.

previous and next properties are returned if there is a next page, though it can happen that these will be present but null. Any URLs for paging will have the same filters, sorts and range settings applied. Anyway, example

{
  "data": [...],
  "paging": {
    "range": 10,
    "total": 14,
    "current_page": 1,
    "next": {
      "title": "Next",
      "href": "https://..."
    }
  }
}

Cursor pagination

On the conversations messages endpoint cursor paging is used. In short this allows us to not rely on the data set remaining consistent, all you need to do is make a request with before or after in the query string. By using either you're saying give me all the data before or after the specified Integer ID.

So, what do you get? Well exactly the same as with offset paging in terms of structure, but an extra but of information. In addition to the previous and next properties in the response (within paging) you'll also get cursors which will have after and before. The point of these bits of data are to give you the IDs of the first and last items in the data set, so when a user scrolls to them or near them you can start loading the previous or next page. Note it is possible that a previous or next property will be returned and the URL may not return any data, or that they'll be there and null missing a title and href property.

Note that the current_page property will be omitted when cursor paging is active.

Here are some links which will probably explain it better...

• http://www.sitepoint.com/paginating-real-time-data-cursor-based-pagination/
• https://developers.facebook.com/docs/graph-api/using-graph-api/v2.4#paging

An example:

{
  "data": [...],
  "paging": {
    "range": 10,
    "total": 14,
    "cursors": {
      "after": 9,
      "before": 0
    }
    "next": {
      "title": "Next",
      "href": "https://..."
    }
  }
}

@todo

• HAL for models.
• Friend list endpoints.

Endpoints

/conversations

{
  "data": [
    {
      "type": "conversation",
      "id": 1,
      "participants": [
        {
          "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,
          "profile": "http://example.com/users/username"
        },
        {
          "type": "user",
          "id": 2,
          "name": "username2",
          "avatars": [
            "100-100": "https://example.com/sites/default/files/styles/cs-100-100/public/avatars/av2.jpg?itok=123",
            "200-200": "https://example.com/sites/default/files/styles/cs-200-200/public/avatars/av2.jpg?itok=123"
          ],
          "contact_frequency": 0,
          profile: "http://example.com/users/username2"
        },
      ],
      "historical_participants": [
        {
          // Same as 'participants' property.
        }
      ],
      "started_by": {
        "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,
          "profile": "http://example.com/users/username"
      }
      "last_updated_by": {
        "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,
          "profile": "http://example.com/users/username"
      }
      "last_message": {
        "type": "message",
        "id": 1,
        "message_type": "cs_pm",
        "conversation_id": 1,
        "sender": {
          "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,
          "profile": "http://example.com/users/username"
        },
        "sent": "",
        "updated": "",
        "text": "Quack quack",
        "weight": 0,
        "edits": 0,
        "deleted": false
      },
      "started": "2015-01-15T12:24:47+0000",
      "updated": "2015-01-15T12:24:47+0000",
      "container": "",
      "title": "",
      "unread_count": 0,
      "pinned": false,
      "archived": false,
      "muted": false,
      "starred": false,
      "forwarded": false,
      "deleted": false
    },
    ...
  ],
  "paging": {
    // See the top of this document for details on pagination.
  }
}

{
  "recipients": [1],
  "text": "Hiiiiiiiiiiiiiiiiiiiiii."
}

Location: /conversations/{conversation_id}

{
  // See conversation model.
}

/conversations/search

{
  "query": "quack"
}

{
  "data": [
    {
      "type": "conversation_search_result",
      "conversation": {
        // See the conversation model.
      },
      "message": {
        // See the message model.
      },
      "relevance": 1.0,
      "page": "https://example.com/api/v1/cs-pm/conversations/1/messages?before=124"
    }
    ...
  ],
  "paging": {
    // See the top of this document for details on pagination.
  }
}

/conversations/{conversation_id}

{
  // See conversation model.
}

/conversations/{conversation_id}/reply

{
  "text": "This is my reply."
}

Location: /conversations/{conversation_id}/message/{message_id}

{
  // See message model.
}

/conversations/{conversation_id}/messages

{
  "data": [
    {
      "type": "message",
      "id": 1,
      "message_type": "comstack_pm",
      "conversation_id": 1,
      "sender": {
        "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,
        "profile": "http://example.com/users/username"
      },
      "sent": "2015-01-15T12:24:47+0000",
      "updated": "2015-01-15T12:24:47+0000",
      "text": "Blah blah...",
      "weight": 0,
      "edits": 0,
      "deleted": false
    },
    ...
  ],
  "paging": {
    // See the top of this document for details on pagination.
  }
}

/conversations/{conversation_id}/messages/delete

{
  "ids": [1, 2]
}

/conversations/{conversation_id}/mark-as-read

/conversations/{conversation_id}/leave

/conversations/{conversation_id}/invite

{
  "ids": [2, 3]
}

/conversations/{conversation_id}/title

{
  "text": "Doddfest 2015 tickets"
}

/conversations/{conversation_id}/mute

/conversations/{conversation_id}/archive

/conversations/{conversation_id}/pin

/conversations/{conversation_id}/star

/conversations/{conversation_id}/search

{
  "query": "tickets"
}

{
  "data": [
    {
      "type": "message_search_result",
      "message": {
        // See the message model.
      },
      "relevance": 1.0,
      "page": "https://example.com/api/v1/cs-pm/conversations/1/messages?before=124"
    }
    ...
  ],
  "paging": {
    // See the top of this document for details on pagination.
  }
}

/users/current-user

{
  "data": {
    "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,
      "profile": "http://example.com/users/username"
    },
    "permissions": {
      "conversations": {
        "start": true,
        "leave": true,
        "reply": true,
        "invite_others": false,
        "set_title": false,
        "mark_as_read": false,
        "mute": false,
        "archive": false,
        "pin": false,
        "start": false
      },
      "messages": {
        "edit_own": false,
        "delete": false
      }
    },
    "preferences": {
      "read_only_mode": false,
      "forced_read_only": false
    }
  }
}

/users/available-users

{
  "data": [
    {
      "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,
      "profile": "http://example.com/users/username"
    },
    ...
  ]
}

/messages/{message_id}

{
  "data": {
    // See the message model.
  }
}

{
  "text": "Quack. Edit to capitalise."
}

{
  "data": {
    // See the message model.
  }
}

Models

Conversation Show details

{
  "type": "conversation",
  "id": 1,
  "participants": [
    {
      "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,
      "profile": "http://example.com/users/username"
    },
    {
      "type": "user",
      "id": 2,
      "name": "username2",
      "avatars": [
        "100-100": "https://example.com/sites/default/files/styles/cs-100-100/public/avatars/av2.jpg?itok=123",
        "200-200": "https://example.com/sites/default/files/styles/cs-200-200/public/avatars/av2.jpg?itok=123"
      ],
      "contact_frequency": 0,
      profile: "http://example.com/users/username2"
    },
  ],
  "historical_participants": [
    {
      // Same as 'participants' property.
    }
  ],
  "started_by": {
    "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,
    "profile": "http://example.com/users/username"
  },
  "last_updated_by": {
    "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,
    "profile": "http://example.com/users/username"
  },
  "last_message": {
    "type": "message",
    "id": 1,
    "message_type": "cs_pm",
    "conversation_id": 1,
    "sender": {
      "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,
      "profile": "http://example.com/users/username"
    },
    "sent": "",
    "updated": "",
    "text": "Quack quack",
    "weight": 0,
    "edits": 0,
    "deleted": false
  },
  "started": "2015-01-15T12:24:47+0000",
  "updated": "2015-01-15T12:24:47+0000",
  "container": "",
  "title": "",
  "unread_count": 0,
  "pinned": false,
  "archived": false,
  "muted": false,
  "forwarded": false,
  "deleted": false
}

Message Show details

{
  "type": "message",
  "id": 1,
  "message_type": "comstack_pm",
  "conversation_id": 1,
  "sender": {
    "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"
    ]
  },
  "sent": "2015-01-15T12:24:47+0000",
  "updated": "2015-01-15T12:24:47+0000",
  "text": "Blah blah...",
  "weight": 0,
  "edits": 0,
  "deleted": false
}

User Show details

{
  "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,
  "profile": "http://example.com/users/username"
}

Conversation search result Show details

{
  "type": "conversation_search_result",
  "conversation": {
    // See the conversation model.
  },
  "message": {
    // See the message model.
  },
  "relevance": 1.0,
  "page": "https://example.com/api/v1/cs-pm/conversations/1/messages?before=124"
}

Within conversation search result Show details

{
  "type": "message_search_result",
  "message": {
    // See the message model.
  },
  "relevance": 1.0,
  "page": "https://example.com/api/v1/cs-pm/conversations/1/messages?before=124"
}