Arena mark

Blocks

Introduction

Blocks are modular and reusable pieces of data or content. A block has primary user (indicated by user_id) and can only be edited by the user who created it. However, any block can be reused in multiple channels (this is called a connection). The channels a block appears in across Arena are listed in the blocks' connections attribute.

These connections are shown depending on the authenticated users access. For example, if a block appears in 5 public channels and 2 private channels, an unauthenticated request will display only the public channels a block appears in, but an authenticated request will show the public channels as well as the private channels that the authenticated user has access to.

Blocks can also take many forms: a text, a link (a captioned link to an external website, with a screenshot), an embed (embeddable media such as a YouTube or Vimeo video), an image (either uploaded from a users' computer or saved from an external website), or an attachment (a file uploaded from a users' computer or from an external website, see also: What file types can I upload to Arena?).

Top

Attributes

id (Integer) The internal ID of the block
title (String, can be null) The title of the block
updated_at (Timestamp) Timestamp when the block was last updated
created_at (Timestamp) Timestamp when the block was created
state (String) Represents the state of the blocks processing lifecycle (this will most often "Available" but can also be "Failure", "Processed", "Processing")
comment_count (Integer) The number of comments on a block
generated_title (String) If the title is present on the block, this will be identical to the title. Otherwise it will be a truncated string of the *description* or *content*. If neither of those are present, it will be "Untitled"
class (String) The type of block. Can be "Image", "Text", "Link", "Embed", or "Attachement"
base_class (String) This will always be "Block"
content (String, can be null) If the block is of class "Text", this will be the text content as markdown
content_html (String, can be null) If the block is of class "Text", this will be the text content as HTML
description (String, can be null) This is used for captioning any type of block. Returns markdown.
description_html (String, can be null) This is used for captioning any type of block. Returns HTML
source (Hash, can be null) If the Block is saved from somewhere on the web, this returns a Hash representation of the source

url (String) The url of the source
provider (Hash) A hash of more info about the provider name: (String) The name of the source provider url: (String) The hostname of the source provider
image (Hash, can be null) If the Block is of class "Image" or "Link", this will be a Hash representation of the various sizes of images that Arena provides (in the case of a "Link" it will be a screenshot of the website).

filename (String) Name of the file as it appears on the Arena filesystem
content_type (String) MIME type of the image (e.g. 'image/png')
updated_at (Timestamp) Timestamp of the last time the file was updated
thumb (Hash) Only contains *url* which is a URL of the thumbnail sized image (200x200)
display (Hash) Only contains *url* which is a URL of the display sized image (same aspect ratio as original image but with a maximim width of 600px or a maximum height of 600px, whichever comes first)
original (Hash) Contains *url* which is a URL of the original image as well file_size (an integer representation in bytes) and file_size_display (a nicer string representation of the file_size)
user (Hash) Representation of the author of the block
connections (Array) An array of hash representations of each of the channels the block appears in
Top

GET /v2/blocks/:id

Returns the full representation of a block


HTTP method: GET
Requires authentication: No

Top

GET /v2/blocks/:id/channels

Returns a paginated list of channels the block exists in


HTTP method: GET
Pagination: Yes
Requires authentication: No

Top

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

Top

PUT /v2/blocks/:id

Resource URL:
http://api.are.na/v2/blocks/:id

Parameters:
:title (optional)

:description (optional)
Markdown formatted text.

:content (optional)
Markdown formatted text. For text block type only.

Updates a block's attributes


HTTP method: PUT
Requires authentication: No

Top

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

Top

DELETE /v2/channel/:channel_id/blocks/:id

Removes a block from the channel it's in (Destroys the connection).


HTTP method: DELETE
Requires authentication: yes

Top