NAME

BusyBird::Manual::WebAPI - Web API reference

DESCRIPTION

This is a reference guide to Web API of BusyBird.

The API paths are based on the path root (/) of the application.

For all HTTP requests with the message body, data format of the body must be JSON encoded by UTF-8, so Content-Type header should be application/json; charset=utf-8.

The data format of HTTP responses is determined by the extension (string after period (.)) of endpoint paths. Text responses are always encoded by UTF-8.

ENDPOINTS

GET /timelines/{timeline}/statuses.{format}

Fetches an array of statuses from the specified timeline. See BusyBird::Manual::Status for the structure of a status object.

Path Parameters

timeline = STR (required)

Timeline name.

format = {json,html} (required)

Response format. It is either json or html.

If html format is specified, the response message is a sequence of HTML <li> elements.

Query Parameters

ack_state = {any,acked,unacked} (optional, default: any)

Specifies the acked/unacked state of the statuses to be fetched.

By setting it to unacked, it returns only unacked statuses from the timeline. By setting it to acked, it returns only acked statuses. By setting it to any, it returns both acked and unacked statuses.

max_id = STATUS_ID (optional, default: none)

Specifies the latest ID of the statuses to be fetched. It fetches statuses with IDs older than or equal to the specified max_id.

If this option is omitted, statuses starting from the latest status are fetched.

count = NUM (optional, default: 20)

Specifies the maximum number of statuses to be fetched.

only_statuses = NUM (optional, default: 0)

If set to 0, which is the default, the response includes statuses and the error message. If set to non-zero, the response is only statuses.

This option is effective only when the format is json. It is useful when you transfer statuses from one BusyBird instance to another.

Response

In success, the HTTP response code is 200.

If format is json and only_statuses is 0, the response is a JSON object. error attribute of the object is null, and statuses attribute is the array of status objects fetched. The array can be empty.
If format is json and only_statuses is non-zero, the response is a JSON array that contains status objects fetched. The array can be empty.
If format is html, the response is a sequence of HTML <li> elements, each of which represents a status object.

In failure, the HTTP response code is 4** or 5**.

If format is json and only_statuses is 0, the response is a JSON object. error attribute of the response object is non-null and it describes the error.
If format is json and only_statuses is non-zero, the response is an empty JSON array.
If format is html, the response is an HTML element describing the error.

Example 1

Request URL:

GET /timelines/home/statuses.json?count=1&ack_state=any&max_id=http://example.com/page/2013/0202

Response Body:

{
  "error": null,
  "statuses": [
    {
      "id": "http://example.com/page/2013/0202",
      "created_at": "Sat Feb 02 17:38:12 +0900 2013",
      "text": "another content"
    }
  ]
}

Example 2

Request URL:

GET /timelines/home/statuses.json?count=1&ack_state=any&max_id=http://example.com/page/2013/0202&only_statuses=1

Response Body:

[
    {
      "id": "http://example.com/page/2013/0202",
      "created_at": "Sat Feb 02 17:38:12 +0900 2013",
      "text": "another content"
    }
]

POST /timelines/{timeline}/ack.json

Acknowledges statuses in the specified timeline, that is, changing 'unacked' statuses into 'acked'. This operation is usually called "mark as read" in other applications. You should ack statuses when you load and display them for the user.

You can set parameters in the request body as a JSON object. If you omit all parameters, you can omit the entire request body.

Path Parameters

timeline = STR (required): Timeline name.

Request Body Parameters

ids = {STATUS_ID, ARRAY_OF_STATUS_IDS} (optional, default: null)

Specifies the IDs of the statuses to be acked.

If it is a string, the status with the specified ID is acked. If it is an array of IDs, the statuses with those IDs are acked.

If both max_id and ids are omitted or set to null, all unacked statuses are acked. If both max_id and ids are specified, both statuses older than or equal to max_id and statuses specifed by ids are acked.

max_id = STATUS_ID (optional, default: null)

Specifies the latest ID of the statuses to be acked.

If specified, unacked statuses with IDs older than or equal to the specified max_id are acked. If there is no unacked status with ID max_id, no status is acked.

Response

The response is a JSON object.

In success, the HTTP response code is 200. error attribute of the response object is null, and count attribute is the number of acked statuses.

In failure, the HTTP response code is 4** or 5**. error attribute of the response object is non-null and it describes the error.

Example

Request URL:

POST /timelines/home/ack.json

Request Body:

{
  "max_id": "http://example.com/page/2013/0202",
  "ids": [
    "http://example.com/page/2013/0204"
   ]
}

Response Body:

{"error": null, "count": 2}

POST /timelines/{timeline}/statuses.json

Adds new statuses to the specified timeline.

This endpoint uses BusyBird::Timeline's add_statuses() method. Therefore, it applies the status filter to the input statuses, and it generates id and created_at fields if they don't exist.

Path Parameters

timeline = STR (required): Timeline name.

Request Body

A status object or an array of status objects in JSON format.

See BusyBird::Manual::Status for the structure of status objects.

Response

The response is a JSON object.

In success, the HTTP response code is 200. error attribute of the response object is null and count attribute is the number of statuses added.

In failure, the HTTP response code is 4** or 5**. error attribute of the response object is non-null and it describes the error.

Example

Request URL:

POST /timelines/home/statuses.json

Request Body:

[
  {
    "id": "http://example.com/page/2013/0204",
    "created_at": "Mon Feb 04 11:02:45 +0900 2013",
    "text": "content of the status",
    "busybird": { "level": 3 }
  },
  {
    "id": "http://example.com/page/2013/0202",
    "created_at": "Sat Feb 02 17:38:12 +0900 2013",
    "text": "another content"
  }
]

Response Body:

{"error": null, "count": 2}

GET /timelines/{timeline}/updates/unacked_counts.json

Watches updates in numbers of unacked statuses (i.e. unacked counts) in the specified timeline, and gets them when necessary.

This is an endpoint for long-polling (Comet) access. The response is delayed until the current unacked counts are different from the unacked counts given in the query parameters.

Path Parameters

timeline = STR (required): Timeline name.

Query Parameters

The query parameters specify the assumed unacked counts. As long as the current unacked counts are the same as the assumed unacked counts, the response is delayed.

The assumed unacked counts can be specified per status level and/or in total.

total = NUM (optional): Specifies the total number of unacked statuses in the timeline.
{level} = NUM (optional): Specifies the number of unacked statuses in the status level of {level}. {level} can be any integer.

Response

The response is a JSON object.

In success, the HTTP response code is 200. error attribute of the response object is null and unacked_counts attribute is an object describing the current unacked counts (See Example).

In failure, the HTTP response code is 4** or 5**. error attribute of the response object is non-null and it describes the error.

Example

Request URL:

The following request means that you assume there are two unacked statuses in 'home' timeline, and they are both in level 0.

GET /timelines/home/updates/unacked_counts.json?total=2&0=2

Response Body:

The server sends back the following response because the current unacked count for level 0 is one instead of two.

{
  "error": null,
  "unacked_counts": {
    "total": 2,
    "0": 1,
    "3": 1
  }
}

GET /updates/unacked_counts.json

Watches updates in numbers of unacked statuses (i.e. unacked counts) in multiple timelines, and gets them when necessary.

This is an endpoint for long-polling (Comet) access. The response is delayed until the current unacked counts are different from the unacked counts given in the query parameters.

Query Parameters

The query parameters specify the assumed unacked counts. As long as the current unacked counts are the same as the assumed unacked counts, the response is delayed.

This endpoint allows you to watch updates in multiple timelines, but you can watch only one status level (or 'total').

level = {total,NUM} (optional, default: total): Specifies the status level to be watched.
tl_{timeline} = NUM (optional): Specifies the unacked counts for the timeline {timeline} in the status level. {timeline} is the name of the timeline you want to watch.

Response

The response is a JSON object.

In success, the HTTP response code is 200. error attribute of the response object is null and unacked_counts attribute is an object describing the current unacked counts (See Example).

In failure, the HTTP response code is 4** or 5**. error attribute of the response object is non-null and it describes the error.

Example

Request URL:

The following request means that you assume there are no unacked statuses in timeline 'home' or timeline 'foobar'.

GET /updates/unacked_counts.json?level=total&tl_home=0&tl_foobar=0

Response Body:

The server sends back the following response because there are two unacked statuses in timeline 'home'.

{
  "error": null,
  "unacked_counts": {
    "home": {
      "total": 2,
      "0": 1,
      "3": 1
    }
  }
}

AUTHOR

Toshio Ito <toshioito [at] cpan.org>

To install BusyBird, copy and paste the appropriate command in to your terminal.

cpanm

cpanm BusyBird

CPAN shell

perl -MCPAN -e shell
install BusyBird

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

ENDPOINTS

GET /timelines/{timeline}/statuses.{format}

POST /timelines/{timeline}/ack.json

POST /timelines/{timeline}/statuses.json

GET /timelines/{timeline}/updates/unacked_counts.json

GET /updates/unacked_counts.json

AUTHOR

Module Install Instructions