Home

Getting Started

bip.io is an open source RESTful JSON API.

It's an API orchestration and http endpoint server. Please see the Installation section of the readme to get a basic server running. If you'd like to take a look at some of the things bip.io can do, sign up to bip.io to explore what's been shared by the community.

The core API of this open source server matches what you'll find on the hosted community platform.

Don't worry, you'll soon be on your way to creating useful bips!

So how does it work?

When you define a bip, you are defining the characteristics of a directed graph.

When a message is received from a web hook, incoming email or generated from a trigger, it appears on a bips graph from the 'source' node. The source data is then normalized into a JSON structure and 'exported' via RabbitMQ for consumption as 'imports' by adjacent nodes. This pipeline continues until all nodes have been visited.

A node in a bip usually represents a Remote Procedure Call (RPC) on an external service, which is a discrete 'action' provided by a 'pod'.

Prior to consumption by an action, imports can be modified in different ways. These modifications are called 'transforms', or 'personalizations' in the UI. As a message is pushed through a graph, an object is built containing exports from visited nodes which can be plucked out with JSONPath. Using these JSONPath expressions and a simple templating system, imports can be composed as you like.

API

The API is namespaced as RESTful resources, and RPC's with /rest and /rpc respectively. JSONP is supported with a callback=your_function GET parameter.

• Endpoints
• Authentication
• REST Endpoints
• RPC Endpoints

Endpoints

If you're running a self-installed instance, endpoints will be namespaced into your config file's domain_public setting, for example :

http://localhost:5000 for modifying system REST and RPC resources https://{username}.localhost:5000 for transacting with your own HTTP Bips and Channel Renderers

For https://bip.io hosted users, bipio has 2 endpoints that you'll likely be using.

https://api.bip.io for modifying system REST and RPC resources https://{username}.bip.io for transacting with your own HTTP Bips and Channel Renderers

Authentication

The API uses HTTP Basic Authentication. Username will be your account username, and password is a generated API token.

curl http://admin:4a4b27ec88763a3c371916d2e23a2000@bipio.local:5000/rest/bip/637658bb-eb15-4d59-9e0e-abb39021e40e

When you set up bip.io for the first time, take note of the generated token for your primary account. If a token has been misplaced, run tools/token_regen.js {account uuid} to regenerate a token for the target account uuid.

You can expose an account UUID by shelling into mongodb and running the appropriate query against the accounts collection.

Response Codes

HTTP Status Codes

400 Error responses will generally be raised due to validation errors in the request payload. Errors are returned within the context of the resource being requested, with the message body of the form errors.{attribute}.message

REST

REST Resources honor GET/POST/PUT/DELETE/PATCH.

• /rest/account_option/:id? POST/DELETE is not supported for account_option.
• /rest/bip/:id?
• /rest/channel/:id?
• /rest/domain/:id?

Decorators

Most REST resources also have additional response decorators attached to each model which provides a little extra info. Decorators are prefixed with an underscore and are read-only. eg: _href : "https://docs.bip.io/rest/bip/bc928113-0a98-4975-a821-98373aa72552"

The two most common are

• _href (URI) Fully Qualified Resource URI
• _repr (String) Derived representation.

Collections

If id has been omitted, GET will return a list of objects. Lists accept page, page_size, order_by GET parameters. The response models are keyed into data.

GET /rest/domain?page=1&page_size=10&order_by=recent

{
  "page": 1,
  "page_size": 10,
  "num_pages": 1,
  "order_by": "recent",
  "total": 2,
  "data": [
    {
      "id": "664616d3-5caf-ab09-b398-000012b5e920",
      "name": "docuser.bip.io",
      "_repr": "docuser.bip.io",
      "_href": "https://api.bip.io/rest/domain/664616d3-5caf-ab09-b398-000012b5e920"
    },
    {
      "id": "61bea7bc-37dd-3368-9b36-00006fa6319e",
      "name": "mydomain.com",
      "_repr": "mydomain.com",
      "_href": "https://api.bip.io/rest/domain/61bea7bc-37dd-3368-9b36-00006fa6319e"
    }
  ]
}

RPC

RPC's provide certain behaviors and helpers for performing work, negotiating authentication or generating content.

• Describe a Model /rpc/describe/:model/:submodel
• Call a Channel Renderer /rpc/render/channel/:channel_id/:renderer
• Negotiate OAuth /rpc/oauth/:pod_name/:auth_method
• Set Credential Tokens /rpc/issuer_token/:pod_name/:auth_method
• Get Referer /rpc/get_referer_hint
• Create Bip from Referer /rpc/bip/create_from_referer
• Get Transform Hint /rpc/bip/get_transform_hint
• Share a Bip /rpc/bip/share
• List Shares /rpc/bip/share/list
• Unshare /rpc/bip/unshare
• Set Account Attribute /rpc/bip/set_default
• Confirm Domain Delegation /rpc/domain/confirm