A Channel is a reusable instance of an action provided by a Pod. When you create a Channel, you are creating an interface to a Pod's action and making it available for use by Bips.

Channels consume and produce content through Imports and Exports. Imports are the structured messages received by the Channel and, after performing its work, the resultant content is then exported in a predictable way.

By themselves, Channels do nothing. See Bips > Hubs to learn how Channels can be put to work.

Parameter Data Type Description
id UUID (String) Unique Channel ID

eg: cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
name * String Unique Channel Name

eg: My Default Email
note String An optional text note to be stored with this record

eg: My personal foobar email that is getting way too much spam
action * String The dot notation form of {pod name}.{action}. See Pods for more info.

eg: email.smtp_forward
config * Object Configuration object for this action. See Pods for more info.

eg: { 'rcpt_to' : 'foo@bar.net' }
Decorators augment a resource record with useful meta-data and are read-only
Parameter Description Example
_href Record URI https://api.bip.io/rest/channel/cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
_repr Derived Channel Representation Post to my Timeline
_available boolean, Channel is available to process messages. Where _available is false, this may mean further action is required. For example, email.smtp_forward require further verification by the intended recipient and are not immediately available.

IMPORTANT Content delivered to unavailable channels will be silently dropped.
_renderers Some channels have their own persistent data source and are able to render the content they've received in a useful way. The available renderers substructure is keyed to a renderer name and subdocument schema containing keys description which is friendly english, content_type for client codec and parsing, and _href which is the URI for invoking the renderer.

@see Renderers in the Channel Pod section for more info.
A syndication.feed renderer:

"_renderers": {
    "rss": {
      "description": "RSS 2.0",
      "contentType": "text/xml",
      "_href": "https://api.bip.io/rpc/render/channel/ba63c4c8-e168-4935-a1cc-a59b1cffed0d/rss"
    }
  }
  

REST Examples

REQUEST
GET /rest/channel/23bb1de5-c950-c448-fbbf-000056c1eed6 HTTP/1.1
RESPONSE
200 OK

{
  "id": "23bb1de5-c950-c448-fbbf-000056c1eed6",
  "name": "Sample",
  "action": "email.smtp_forward",
  "config": {
    "rcpt_to": "foo@bar.net",
    "icon_url": "https://docs.bip.io/avatar/photo.png"
  },
  "_available": true,
  "note": "Default Email Forwarder For Docs Account",
  "_repr": "Forward to undefined",
  "_href": "https://api.bip.io/rest/channel/23bb1de5-c950-c448-fbbf-000056c1eed6"
}

REQUEST
POST /rest/channel HTTP/1.1

{
  "name": "Sample",
  "action": "email.smtp_forward",
  "config": {
    "rcpt_to": "foo@bar.net",
    "icon_url": "https://docs.bip.io/avatar/photo.png"
  },
  "note": "Default Email For Docs Account"
}
RESPONSE
202 Accepted

{
  "id": "23bb1de5-c950-c448-fbbf-000056c1eed6",
  "name": "Sample",
  "action": "email.smtp_forward",
  "config": {
    "rcpt_to": "foo@bar.net",
    "icon_url": "https://docs.bip.io/avatar/photo.png"
  },
  "_available": true,
  "note": "Default Email For Docs Account",
  "_repr": "Forward to foo@bar.net",
  "_href": "https://api.bip.io/rest/channel/23bb1de5-c950-c448-fbbf-000056c1eed6"
}

REQUEST
PUT /rest/channel HTTP/1.1

{
  "id": "23bb1de5-c950-c448-fbbf-000056c1eed6",
  "name": "Sample",
  "action": "email.smtp_forward",
  "config": {
    "rcpt_to": "support@bip.io",
    "icon_url": "https://docs.bip.io/avatar/photo.png"
  },
  "note": "Default Email For Docs Account"
}
RESPONSE
200 OK

{
  "id": "23bb1de5-c950-c448-fbbf-000056c1eed6",
  "name": "Sample",
  "action": "email.smtp_forward",
  "config": {
    "rcpt_to": "support@bip.io",
    "icon_url": "https://docs.bip.io/avatar/photo.png"
  },
  "_available": true,
  "note": "Default Email For Docs Account",
  "_repr": "Forward to support@bip.io",
  "_href": "https://api.bip.io/rest/channel/23bb1de5-c950-c448-fbbf-000056c1eed6"
}

REQUEST
DELETE /rest/channel/23bb1de5-c950-c448-fbbf-000056c1eed6 HTTP/1.1
RESPONSE
200 OK

comments powered by Disqus