Channels

Introduction

Channels are organizational structures for content. This means blocks but also sometimes other channels. Channels have a primary user (indicated by the user_id) but can also have collaborators (an array of users). Channels can be public (anyone can view and add), closed (only the channel's author and collaborators can add but everyone can view) and private (only the channels authors and collaborators can view and add).

See also: What is a channel?

Attributes

id (Integer) The internal ID of the channel
title (String) The title of the channel
created_at (Timestamp) Timestamp when the channel was created
updated_at (Timestamp) Timestamp when the channel was last updated
published (Boolean) If channel is visible to all members of arena or not
open (Boolean) If channel is open to other members of arena for adding blocks
collaboration (Boolean) If the channel has collaborators or not
slug (String) The slug of the channel used in the url (e.g. http://are.na/arena-influences)
length (Integer) The number of items in a channel (blocks and other channels)
kind (String) Can be either "default" (a standard channel) or "profile" the default channel of a user
status (String) Can be "private" (only open for reading and adding to the channel by channel author and collaborators), "closed" (open for reading by everyone, only channel author and collaborators can add) or "public" (everyone can read and add to the channel)
user_id (Integer) Internal ID of the channel author
class (String) Will always be "Channel"
base_class (String) Will always be "Channel"
user (Hash) More information on the channel author. Contains id, slug, first_name, last_name, full_name, avatar, email, channel_count, following_count, follower_count, and profile_id
total_pages (Integer) If pagination is used, how many total pages there are in your request
current_page (Integer) If pagination is used, page requested
per (Integer) If pagination is used, items per page requested
follower_count (Integer) Number of followers the channel has
contents (Array, can be null) Array of blocks and other channels in the channel. Note: If the request is authenticated, this will include any private channels included in the requested channel that you have access to. If not, only public channels included in the requested channel will be shown.
collaborators (Array, can be null) Collaborators on the channel

Block attributes

Blocks inside the channel's contents node have attributes that are specific to the channel:

position (Integer) The position of the block inside the channel (as determined by the channel's author and collaborators)
selected (Boolean) Block is marked as selected inside the channel (this is an initial attempt to allow users to "feature" some content over others, can be used for moderation, introduction text, etc)
connected_at (Timestamp) Time when block was connected to the channel (if the block was created at the same time as the channel this will be identical to created_at)
connected_by_user_id (Integer) ID of the user who connected the block to the channel (if the block was not reused by another user, this will be identical to user_id)

GET /v2/channels

Returns a list of published channels.


HTTP method: GET
Pagination: Yes
Requires authentication: No

GET /v2/channels/:slug

Returns a complete representation of a channel. Channel contents can be paginated.


HTTP method: GET
Pagination: Yes
Requires authentication: No

GET /v2/channels/:slug/thumb

Returns some fixed basic information for constructing a small channel representation. For now: returns the first 9 blocks of the channel. This may change.


HTTP method: GET
Pagination: No
Requires authentication: No

GET /v2/channels/:id/connections

Returns all the connections within a channel without fetching actual objects.


HTTP method: GET
Pagination: Yes
Requires authentication: No

GET /v2/channels/:id/connections

Returns all of the channels connected to blocks in the channel. For instance if one wanted to spider the connections between channels


HTTP method: GET
Pagination: Yes
Requires authentication: No

GET /v2/channels/:id/contents

Returns all the contents of a channel. Nothing else (collaborators, etc.)


HTTP method: GET
Pagination: Yes
Requires authentication: No

POST /v2/channels

Resource URL:
http://api.are.na/v2/channels

Parameters:
:title (required)
Title of the channel

:status (optional)
Sets the visibility of the channel. Can be: ["public", "closed", "private"]
Defaults to "public"

Creates a new channel


HTTP Method: POST
Requires authentication: Yes

PUT /v2/channels/:slug

Resource URL:
http://api.are.na/v2/channels/:slug

Parameters:
:title (optional)
Title of the channel

:status (optional)
Sets the visibility of the channel. Can be: ["public", "closed", "private"]
Defaults to "public"

Updates the channels attributes


HTTP Method: PUT
Requires authentication: Yes

PUT /v2/channels/:slug/sort

Resource URL:
http://api.are.na/v2/channels/:slug/sort

Parameters:
:ids (required)
Serialized array of IDs

Accepts a serialized array of IDs. Updates the order of the channel to the order of the IDs.


HTTP method: PUT
Requires authentication: Yes

DELETE /v2/channels/:slug

Destroys the channel and connections to content. Content contained within is not destroyed.


HTTP method: DELETE
Requires authentication: Yes

POST /v2/channels/:slug/blocks

Resource URL:
http://api.are.na/v2/channels/:slug/blocks

Parameters:
:source (required*)
URL of content. Can be an Image, Embed, or Link.

:content (required*)
Textual content that's rendered with Github Flavored Markdown.

Either *:source or :content is required. Not both.

Creates a new block and adds it to the specified channel.


HTTP method: POST
Requires authentication: Yes

PUT /v2/channels/:channel_id/blocks/:id/selection

Toggles selected status of a block (or more specifically, it's connection to the channel)


HTTP method: PUT
Requires authentication: Yes

GET /v2/channels/:id/collaborators

Returns all members that are part of a channel. Does not return channel owner


HTTP method: GET
Requires authentication: No

POST /v2/channels/:id/collaborators

Accepts a serialized list of ids. Returns the current list of collaborators


HTTP method: POST
Requires authentication: Yes

DELETE /v2/channels/:id/collaborators

Accepts a serialized list of ids. Include only the ids you want to keep in the channel, excluding the ones you want to delete. Returns the current list of collaborators


HTTP method: DELETE
Requires authentication: Yes