Overview

The Coub web API allows you to send and retrieve data from the Coub server via HTTP requests and responses. Almost all of Coub's features are available through the API, such as querying and managing user and channel data, uploading coub videos, searching for a video or channel, and much more.

Any application that is able to use the HTTP can communicate with the Coub server simply by requesting the correct URL (also refered to as the endpoint).

Each HTTP request consists of an HTTP method, a URL, and usually a set of parameters.

The server receives HTTP requests containing data usually defined as URL parameters, specific to each method, and sends responses in the JSON format.

An authorization for the Coub web API is provided by the OAuth authentication protocol. Coub uses the second version of this protocol — OAuth 2.0.

Methods

The Coub server expects an appropriate HTTP method for each type of the required action:

  • GET — to retrieve data;
  • PUT — to update data;
  • POST — to add data;
  • DELETE — to delete data.

Endpoints

The endpoint is the unique identifier of the Coub web API resource which request messages can be addressed to. For example, this is the endpoint for the notifications resource:

/api/v2/notifications

Some endpoints may require parameters. For example, this endpoint, which responds with a coub's data, requires the id of the coub:

/api/v2/coubs/:id.json

To make an API request you need to append an endpoint to the Coub server URL address — http://coub.com.

For example, if the required endpoint is /api/v2/channels/notifications_viewed, than the request URL should be as follows:

http://coub.com/api/v2/channels/notifications_viewed

Request parameters

Using query attributes

Most POST, PUT and some GET requests must contain parameters, depending on the HTTP method and the endpoint URL. An authentication token should also be added as a request parameter (for clarity, access_token parameter, that contains authentication token, has been omitted from request examples of this reference).

The default way of passing parameters is by using standard query attributes — appending parameters to the end of the URL.

In this case, the URL should ends with a question mark "?", and each parameter and its attributes should be defined in the form of "key=value" pairs, separated with a "&" mark.

GET /api/v2/likes/by_channel?channel_id=1164719

As a JSON object

The other way to pass parameters is by sending a JSON object containing parameter names and values as key-value pairs. In this case, the Content-Type header of the request should be set to application/json.

POST http://coub.com/api/v2/recoubs
Content-Type: application/json

{"recoub_to_id":"5113938","channel_id":"1223359"}

Response codes

The Coub server replies to a request with an HTTP response that, besides response JSON data, has one of the standard HTTP status codes:

  • 200 — The request succeeded.
  • 403 — Access Denied. The reason may be: current access mode forbids access to a requested resource, or the access token is invalid/exceeded.
  • 404 — The resource is not found.
  • 422 — Invalid input data. Usually this status code is returned on PUT, POST or DELETE requests.
  • 42Х — Different errors codes.
  • 500 — Some server error.