A Bip is a very fast and light weight endpoint definition for your personal domain(s) that receives, transforms and distributes messages across a distributed graph. It has an endpoint type, a unique name, some type specific configuration, and an action graph (or Hub).

Try keeping these characteristics in mind


Dynamic By omitting the 'name' parameter, a short, unique name will be generated in place, similar to how a link shortener works. You can also use the create_from_referer RPC helper to generate a bip whose name is derived from a parseable domain referer, such as an external website or email address. This lets you bind bips to certain content providers, or generate things like moderated email aliases, like the Chrome Plugin does for signup forms.

Lifelike Bips can be configured to expire automatically after a certain time or impressions volume (hits) basis. Expired Bips are automatically paused by default, and paused bips will silently drop any message they receive. This behaviour can be tweaked as an Account Option. Lifetimes are useful if you want to automatically moderate the volume of messages received on a bip and not have to think about it.

Faithful Its easy to bind one message sender to a bip and ignore all others, simply set a binder option, and that sender will have an exclusive lock on your bip for its lifetime, or is otherwise reconfigured/ Binder's aren't true ACL's however, they should be used in conjunction with Bip specific authentication

Consistent Bips are just like Channels such they import and export messages for processing. Think of SMTP or HTTP Bips as being special case channels able to receive data from anywhere and fire a realtime event. A Bips hub and associated transform can be modified any time via a PUT request, changing the delivery strategy of a bip without modifying its endpoint in your application.
Parameter Data Type Description
id UUID (string) Unique Bip ID

eg: cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
name String, alphanumeric, '_' Unique Bip Name. Any name provided is normalised to lowercase, alphanumeric with '_' in place of spaces.
Leave empty to generate a random, unique name

eg: great_startups
domain_id UUID String,

default account_option.bip_domain_id
Domain Id.

eg: cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
type String

default account_option.bip_type
Bip type, where
  • smtp accepts content via email
  • http is via HTTP(s)
  • trigger is a periodic event
@see the config attribute for more info

eg: smtp
config** Object type dependant config. See Type Configs section below, for the type you wish to configure.
hub Object

default account_option.bip_hub
Graph and Import Transform structure. See Hubs section below.
'source' : {
        edges : [ 'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' ],
        transforms : {
            'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' : {
                'subject' : 'title'
            }
        }
    }
                        
note String An optional text note to be stored with this record
my tacocopter.com beta invite address
end_life Object,

default account_option.bip_end_life
Expiry structure, keyed to
  • time any datejs parseable time
  • imp maximum impressions
Bips will automatically pause when these limits are reached. Set as '0' for each of time or impressions to disable these limits.

IMPORTANT Times are stored and enforced based on your account_option.timezone setting.

eg:
{
  'time' : '+1m',
  'imp' : 50
}
                        
paused Booelan, default false bip has been paused, does not accept or generate any content.
false
binder Array smtp or http bip types only, is an array of sender email addresses or Client IP's, respectively. Binders are soft validators that only accept connections from these clients over the bips lifetime. To bind with the first connection that is made use an array of length 1 containing the string 'first'.
[ 'noreply@mydomain.com' ] or
[ '75.19.207.20' ] or
[ 'first' ]
icon String Image URL which can be rendered for this bip
** You read right, no fields are required to create a bip, except a config parameter when using a trigger. We'll otherwise fill any blanks in the request structure with your configured Account Options and a randomized name.
Decorators augment a resource record with useful meta-data and are read-only
Parameter Description Example
_href Record URI https://api.bip.io/rest/bip/cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
_repr Derived Bip Representation great_startups@docs.bip.io
_imp_actual Actual Impressions, the number of messages received by this bip 349587

REST Examples

REQUEST
GET /rest/bip/bc928113-0a98-4975-a821-98373aa72552 HTTP/1.1
RESPONSE
200 OK

{
    id: "bc928113-0a98-4975-a821-98373aa72551",
    name: "test",
    domain_id: "31b3a2db-4ea4-d1c8-b35d-00004d00b4d7",
    type: "smtp",
    config: { },
    hub: {
        source: {
            edges: [
                "05de2c02-7ec6-4be8-d3db-00006a8ed73e"
                ]
            }
    },
    note: "sample smtp bip",
    end_life: {
        time: 0,
        imp: 0
    },
    paused: false,
    icon: "",
    created: "1358816085282",
    _imp_actual: 14,
    _repr: "test@docs.bip.io",
    _href: "https://api.bip.io/rest/bip/bc928113-0a98-4975-a821-98373aa72552"
}

            
REQUEST
POST /rest/bip HTTP/1.1

{
    name: "test",
    type: "smtp",
    note: "sample smtp bip",
    end_life: {
        time: 0,
        imp: 0
    },
    _comment: "This sample overrides end_life, type and name but uses account defaults otherwise"
}
RESPONSE
201 Created

{
    id: "bc928113-0a98-4975-a821-98373aa72551",
    name: "test",
    domain_id: "31b3a2db-4ea4-d1c8-b35d-00004d00b4d7",
    type: "smtp",
    config: { },
    hub: {
        source: {
            edges: [
                "05de2c02-7ec6-4be8-d3db-00006a8ed73e"
                ]
            }
    },
    note: "sample smtp bip",
    end_life: {
        time: 0,
        imp: 0
    },
    paused: false,
    icon: "",
    created: "1358816085282",
    _imp_actual: 0,
    _repr: "test@docs.bip.io",
    _href: "https://api.bip.io/rest/bip/bc928113-0a98-4975-a821-98373aa72552"
}

            
REQUEST
PUT /rest/bip HTTP/1.1

{
    id: "bc928113-0a98-4975-a821-98373aa72551",
    name: "test",
    type: "smtp",
    note: "sample smtp bip - now we're expiring",
    end_life: {
        time: +1m,
        imp: 100
    }
}
RESPONSE
200 OK

{
    id: "bc928113-0a98-4975-a821-98373aa72551",
    name: "test",
    domain_id: "31b3a2db-4ea4-d1c8-b35d-00004d00b4d7",
    type: "smtp",
    config: { },
    hub: {
        source: {
            edges: [
                "05de2c02-7ec6-4be8-d3db-00006a8ed73e"
                ]
            }
    },
    note: "sample smtp bip - now we're expiring",
    end_life: {
        time: 1361494485282,
        imp: 100
    },
    paused: false,
    icon: "",
    created: "1358816085282",
    _imp_actual: 14,
    _repr: "test@docs.bip.io",
    _href: "https://api.bip.io/rest/bip/bc928113-0a98-4975-a821-98373aa72552"
}

            
REQUEST
DELETE /rest/bip/bc928113-0a98-4975-a821-98373aa72552 HTTP/1.1
RESPONSE
200 OK

Every Bip requires a type, and a config for that type, and each type has its own exports. An Export is the message packet a Bip (or Channel) sends for transform and delivery to adjacent channels in a hub.

In addition to Type specific exports, all Bips may also export :
Parameter Data Type Description
_files array An array of file attachment meta data, of the form
{
    name : 'file name',
    size : 'size in bytes',
    type : 'file extension, lowercase'
}
                            
_client#{attribute} string Originating client identifier attribute, where attribute is one of :
  • host Remote Host IP
  • repr Message producer symbol, for smtp it will be the sending email address, for http it will be the IP. sender from a Trigger will be marked with the Channels pod.action

eg: _client.repr export value of hipchat.instruction
_bip#{attribute} string Originating Bip attributes, where attribute is a Bip datapoint of name, type, config, _repr.
eg: _bip#repr export value of https://docs.bip.io/bip/http/test_this

Available Types

A trigger is a special type of Bip with a Channel as its source. It does not get pushed content but rather requests content from a Channel every 10 minutes. Generating content when someone posts a new message to your Facebook wall is an example of a Trigger Bip with a (Facebook) channel source.

To check which of your configured channels can be used as triggers, GET /rest/channel/emitters.

Config
Parameter Description
channel_id Triggering Channel Id, must be a Channel where _emitter : true

eg: cf01c8ec-e542-46ce-9895-74b6ea3fcf5b
Exports
Parameter Data Type Description
? mixed Trigger exports are inherited from the configured Channel (channel_id). See the configured Channel's exports to derive an appropriate source transform.

SMTP Bips are email aliases for your domain(s), which deliver content. They might be dedicated to handling alert emails, processing incoming enquiry leads, or moderating an untrusted email sender.

Config
No config is required for SMTP Bips.

Send messages to SMTP Bips via

{bip name}@{username}.bip.io

Exports
Parameter Data Type Description
body_html string HTML body, if available
body_text string Text body, if available
subject string Subject, if available

HTTP Bips are named endpoints you can GET or POST content to via the HTTPS protocol.

Config
Message HTTP Bips via

https://{username}.bip.io/bip/http/{bip name}

Parameter Description
exports Array of named attributes to transform. These named attributes are hints for transformation against GET parameters supplied when invoking the Bip, or JSON decoded body data. Export hints for embedded objects (eg: { some_object : { abc : "123" } }) are not currently supported.

The system provides two default exports 'for free' which are interpreted as query parameters for the purpose of generating transforms:

  • title A message title
  • body Message body


eg: [ 'message' ]
auth Auth means the HTTP Basic Auth credentials that are required by a client of this HTTP bip.

String of type
  • none Disables authentication
  • token To use default account token (Basic Auth)
  • basic To use custom username/password (Basic Auth)
    IMPORTANT we strongly advise to use either 'basic' or 'none' authentication strategy to minimize the risk of your account level API token being exposed.

eg: auth : 'none'
username Auth Username, where auth : basic
password Auth Password, where auth : basic
renderer Allows Bips to serve Channel content directly while inheriting 'bip-like' characteristics (lifespan, custom credentials etc)

Object keyed by :
  • channel_id Target Channel Id
  • renderer Renderer name
  • query Additional URI GET query string
eg:
 {
    "channel_id" : "cf01c8ec-e542-46ce-9895-74b6ea3fcf5b",
    "renderer" : "csv"
}

HTTP Bips with a renderer setting make hub configs non-mandatory
Exports HTTP Exports
Parameter Data Type Description
? mixed HTTP Bips export whatever parameters they receive. Hint the exports for transform with the exports configuration helper.
A 'Hub' is a graph structure of vertices (Channels) and directed edges (transforms) for mapping the exports of one Channel to the imports of an adjacent Channel. A Hub may describe for example, how to transform a file upload such that it can be instantly saved to Dropbox.

In a nutshell, Hubs describe the delivery strategy for a Bip.

Hub Validation Rules


Edges are singly directed For the meantime, edges can be defined for any vertices of outdegree >= 1, and indegree 1. Directionality is therefore implicit to the outdegree of the source vertex, which is always a Bip of type:smtp, type:http or type:trigger or a defined Channel vertex with an existing edge.

Loops or multiple edge dependencies (indegree > 1) are currently not supported.

Transforms are not Mandatory By setting a transform value of default, the system will do its best to infer a proper transform between channels based on a democratic best-guess. This transform will be unpacked during the save process, and can be tweaked on subsequent PUT requests.
The Hub graph structure is an object keyed by channel id, each with a substructure detailing edges and transforms to adjacent upstream channels.

Edges are keyed to the originating Channel Id, Transforms are simply an export => import map from one Channel's exports, to the adjacent Channels imports. source is a special case vertex which indicates that messages are originating from the Bip via smtp,http or a channel trigger. Hubs require a source with at least 1 edge.



For Example, a HTTP Bip which delivers to an email.smtp_forward Channel may look like this :
'source' : {
        edges : [ 'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' ],
        transforms : {
            'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' : {
                'subject' : 'title' // transform Email
            }
        }
    }
Or more simply if the originating source was a type: smtp bip and did not require any transforms (simple message proxy), we could use the simplest possible graph.
 'source' : { edges : [ 'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' ] }

A more complex example, with a HTTP Bip exporting to an email and an optionally filtered RSS Channel
'source' : { // << bip source
    edges : [
            'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b', // Email Channel
            'ba63c4c8-e168-4935-a1cc-a59b1cffed0d' // Filter Channel
            ],
    transforms : {
        'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' : {
            'subject' : 'title' // transform Email
        }
        // !! no transform for Filter - simply proxy the export !!
    }
},
'ba63c4c8-e168-4935-a1cc-a59b1cffed0d' : {   // Filter source Channel Id
    edges : [ '74b6ea3f-cf5b-cf01-c8ec-e54246ce9895' ], // RSS Channel
    transforms : {
        '74b6ea3f-cf5b-cf01-c8ec-e54246ce9895' : 'default' // default map
    }
}
NOTE There are two content producers in the above example which needed their content transformed, source and Filter (ba63c4c8-e168-4935-a1cc-a59b1cffed0d)
Parameter Data Type Description
edges** Array List of channels that this source channel will export to.

eg: [ "cf01c8ec-e542-46ce-9895-74b6ea3fcf5b" ]
transforms Object Object keyed to an edge channel id, containing either Key/Value pairs describing the exports for this source, and how they map to imports across an edge, or reserved strings of
  • default to use a system provided transform
eg:
transforms : {
    'cf01c8ec-e542-46ce-9895-74b6ea3fcf5b' : {
        'import' : 'export'
    }
    'ba63c4c8-e168-4935-a1cc-a59b1cffed0d' : 'default'
}
                                
By Omitting a transform, exports will remain unmodified across the edge.

Transforms are Hub attributes for mapping the exports and imports between adjacent Channels in the graph. They're a key/value collection where key is the target import, and value is the source export template. Exports can be literal imports or interpolated into templates, of the form [% attribute %]. Template variables can be derived from any available upstream export.

Exports which can not be found as export literals in their originating channels will be interpreted as templated text, and therefore do not raise any validation errors.

To reference an export from a non-adjacent channel, simply reference the channel id and export with hash (#) delimiters. For example, "body" : "cf01c8ec-e542-46ce-9895-74b6ea3fcf5b#body" Imports upstream Channel cf01c8ec-e542-46ce-9895-74b6ea3fcf5b's body export into the local import.

For example, a transform with literals and templates

transforms : {    
    'ba63c4c8-e168-4935-a1cc-a59b1cffed0d' : {
        "reply_to" : "from",
        "rcpt_to" : "cf01c8ec-e542-46ce-9895-74b6ea3fcf5b.mail_from",
        "subject" : "Hi there [% name %] we got your email via [% _bip#name %] from IP [% _client#host %]"
    }
}
            


comments powered by Disqus