Developer
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
Resource URL:
http://api.are.na/v2/channels
Example Request:
GET http://api.are.na/v2/channels?page=2&per=15
Returns a list of published channels.
HTTP method: GET
Pagination: Yes
Requires authentication: No
GET /v2/channels/:slug
Resource URL:
http://api.are.na/v2/channels/:slug
Example Request:
GET http://api.are.na/v2/channels/faq
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
Resource URL:
http://api.are.na/v2/channels/:slug/thumb
Example Request:
GET http://api.are.na/v2/channels/arena-influences/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
Resource URL:
http://api.are.na/v2/channels/:id/connections
Example Request:
GET http://api.are.na/v2/channels/arena-influences/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
Resource URL:
http://api.are.na/v2/channels/:id/channels
Example Request:
GET http://api.are.na/v2/channels/arena-influences/channels
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
Resource URL:
http://api.are.na/v2/channels/:id/contents
Example Request:
GET http://api.are.na/v2/channels/arena-influences/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
Resource URL:
http://api.are.na/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
Resource URL:
http://api.are.na/v2/channels/:slug/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
Resource URL:
http://api.are.na/v2/channels/:slug/collaborators
Example Request:
GET http://api.are.na/v2/channels/arena-influences/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
Resource URL:
http://api.are.na/v2/channels/:slug/collaborators
Example Request:
POST http://api.are.na/v2/channels/arena-influences/collaborators
Accepts a serialized list of ids. Returns the current list of collaborators
HTTP method: POST
Requires authentication: Yes
DELETE /v2/channels/:id/collaborators
Resource URL:
http://api.are.na/v2/channels/:slug/collaborators
Example Request:
DELETE http://api.are.na/v2/channels/arena-influences/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