Skip to content

Home

Jump to bottom Edit New page
Michael J Pearson edited this page Dec 2, 2015 · 113 revisions

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, browse the cookbook in the sidebar or sign up to bip.io explore what's been shared by the community.

This open source server API matches what you'll find on the hosted community platform.

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

Contents

Useful why?

There are many reasons to use an ephemeral graph system, here's some highlights

  • message delivery implementations are trivial to refactor as vertices can be swapped in-place dynamically. Changes to client code is highly unlikely.

  • vertices in the graphs have no other system concerns but the 'one thing they do well', given knowledge of immediately adjacent edges they have everything they need to scale horizontally and vertically.

  • graph structures are a natural fit for a pipe and filter pattern, as they can visually describe messsage pathways and model potentially complex workflows.

  • once a Bip expires or is otherwised removed, replays are impossible. On expiry, Bips disappear forever, this means temporal endpoints cannot be discovered or interrogated. for example : /bip/http/abc123 may do abc, or 123, or xyz, and it may or may not exist. Similarly nothing about the endpoint needs to have a name with any semantic value. The underlying delivery strategy for a single endpoint may be constantly changing.

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 and are generally referred to as 'actions'.

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.

A note on files

Received or fetched files are not present as explicit imports/exports but rather appear on a graph as they become available. Certain actions will operate with the assumption that these files are present eg: Dropbox > Save File will only run when a file is present.

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

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:[email protected]: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.

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.

Add a custom footer

Wiki Home

Core

Tutorials

Cookbook

Modules

Extras

Clone this wiki locally