Honbu REST Web Service Interface

Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

All API calls to Honbu must be secured over HTTPS. The baseurl to use would be https://app.honbu.io/...

Register a User

Creates a new user account.

url:
api/users.json
Request Type:
Post
Request:
{ 
	user: {
		email: "[string]", 
		password: "[string]", 
		forename: "[string]", 
		surname: "[string]"
	}
}
Response:
{ 
	success: true, 
	auth_token: "[string]",
	email: "[string]"
}


Creates a new user account (with api_key).

url:
api/users.json
Request Type:
Post
Request:
{ 
	key: "[string]",
 	user: {
		email: "[string]", 
		forename: "[string]", 
		surname: "[string]"
	}
}
Response:
{ 
	success: true,
	auth_token: "[string]", 
	email: "[string]" 
}

Sign in a User

Creates a new user session

url:
api/users/sign_in.json
Request Type:
Post
Request:
{ 
	user: {
		email: "[string]", 
		password: "[string]", 
		remember_me: [integer]
	}
}
Response:
{ 
	success: true, 
	auth_token: "[string]",
	email: "[string]" 
}


Creates a new user session (with api_key).

url:
api/users/sign_in.json
Request Type:
Post
Request:
{ 
	key: "[string]",
	user: {
		email: "[string]", 
		remember_me: [integer]
	}
}
Response:
{ 
	success: true, 
	auth_token: "[string]",
	email: "[string]"
}

Sign out a User

Destroys the users session

url:
api/users/sign_out.json
Request Type:
Post
Request:
{ user: {
	email: "[string]", 
	auth_token: "[string]"
	}
}
Response:
{ 
	success: true 
}

Find a User

Returns a single user account

url:
api/users/find
Request Type:
POST
Request:
{	
	auth_token: "[string]",
	email: "[string]"
}
Response:
[
    {
        id: [integer],
        forename: "[string]",
        surname: "[string]",
        job_title: "[string]",
        email: "[string]",
        avatar_file_name: "[string]",
        avatar_file_size: "[string]",
        avatar_content_type: "[string]"
    }
]

Update a User

Update a users profile

url:
api/users/[user_id]
Request Type:
PUT
Request:
{  
  auth_token: "[string]",
  user: { 
  	forename: "[string]",
  	surname: "[string]",
  	job_title: [string],
  	avatar_file_name: "[string]"
  }
}

Note - "avatar_file_name" must be a valid url of an avatar image (.png, .jpg or .gif). Honbu will automatically grab a copy of the image and set it to the users account.

Response:
[
    {
        id: [integer],
        forename: "[string]",
        surname: "[string]",
        job_title: "[string]",
        email: "[string]",
        avatar_file_name: "[string]",
        avatar_file_size: "[string]",
        avatar_content_type: "[string]"
    }
]

View Public Streams

Returns a list of all the public streams

url:
api/streams.json
Request Type:
Get
Request:
BLANK
Response:
[
    {
        id: [integer],
        name: "[string]",
        description: "[string]",
        user_id: [integer],
        created_at: "[datetime]",
        updated_at: "[datetime]"
    }
]

Create a Stream

Creates a new stream on behalf of the authenticated user.

Note* The user who creates the new stream will be auto-joined as a member of that stream.

url:
api/streams.json
Request Type:
Post
Request:
{ auth_token: "[string]",
  stream: { 
  	name: "[string]",
  	description: "[string]",
  	private: [integer],
  	unique_url: "[string]"
  }
}
Response:
{	
	id: [integer],
	name: "[string]",
	description: "[string]",
	unique_url: "[string]",
	user_id: [integer],
	created_at:"[datetime]",
	updated_at: "[string]"
}

Update a Stream

Update a stream

url:
api/streams/[stream_id]
Request Type:
PUT
Request:
{  
  auth_token: "[string]",
  stream: { 
  	name: "[string]",
  	description: "[string]",
  	private: [integer],
  	unique_url: "[string]"
  }
}
Response:
{	
	id: [integer],
	name: "[string]",
	description: "[string]",
	unique_url: "[string]",
	user_id: [integer],
	created_at:"[datetime]",
	updated_at: "[string]"
}

Delete a Stream

Deletes a stream which has been created by the authenticated user only.

url:
api/streams.json
Request Type:
Post
Request:
{	
	auth_token: "[string]",
	stream: { 
		id: [integer] 
	},
	_method : "delete"
}
Response:
{	success: true,
	stream_id: [integer]
}

Add Member to Stream

Adds the authenticated user to a stream.

url:
api/streams/:id/members.json
Request Type:
Post
Request:
{	
	auth_token: "[string]",
	member: { 
		id: [integer],
		can_manage_users: [true/false]
	}
}
Response:
{	
	embed_token: "[string]",
}

Remove Members from Stream

Removes the authenticated user from a stream

url:
api/streams/:id/members.json
Request Type:
Post
Request:
{	
	auth_token: "[string]",
	member: { 
		id: [integer/] 	//user_id 
	},
	_method : "delete"
}
Response:
{ 
	success: true 
}

View Streams a Member has

Returns a list of all the streams that the authenticated user is a member of.

url:
api/users/:id/streams.json
Request Type:
Get
Request:
BLANK
Response:
[
    {   
        id: [integer],
        name: "[string]",
        description: "[string]",
        user_id: [integer],
        created_at: "[datetime]",
        updated_at: "[datetime]"
    }
 ]

View all Members within a Stream

Returns a list of all the members belonging to a stream. The authenticated user must already be a member of the requested stream.

url:
api/streams/:id/members.json
Request Type:
Get
Request:
BLANK
Response:
[
    {
        id: [integer],
        workspace_id: [integer],
        user_id: [integer],
        can_manage_users: [integer],
        updated_at: "[datetime]",
        created_at: "[datetime]"
    }
]

View Posts belonging to a User

Returns a list of posts created by the user. Only the authenticated user will return posts created in private streams.

url:
api/users/:id/posts.json
Request Type:
Get
Request:
BLANK
Response:
[
    {
    	id: [integer],
        content: "[text]",
        workspace_id: [integer],
        user_id: [integer],
        share_link_active: [true/false],
        share_secure_link: "[string]",
        comments: {...},
        assets: {...},
        enrichments: {...},
        created_at: "[datetime]",
        updated_at: "[datetime]"
    }
]

View Posts belonging to a Stream

Returns a list of posts belonging to a given stream. Private stream posts will only be returned for the authenticated user.

url:
api/streams/:id/posts.json
Request Type:
Get
Request:
BLANK
Response:
[
    {
    	id: [integer],
        content: "[text]",
        workspace_id: [integer],
        user_id: [integer],
        share_link_active: [true/false],
        share_secure_link: "[string]",
        comments: {...},
        assets: {...},
        enrichments: {...},
        created_at: "[datetime]",
        updated_at: "[datetime]"
    }
]

View a Users favourite posts

Returns a list of posts that the authenticated user has favourited.

url:
api/users/:id/favourites.json
Request Type:
Get
Request:
BLANK
Response:
[
    {
    	id: [integer],
        content: "[text]",
        workspace_id: [integer],
        user_id: [integer],
        share_link_active: [true/false],
        share_secure_link: "[string]",
        created_at: "[datetime]",
        updated_at: "[datetime]"
    }
]

Create New Post

Create a new post within a given stream.

url:
api/posts
Request Type:
POST
Request:
{
    post {
    	content: "[text]",
    	workspace_id: [integer]
    }
}
Response:
{
    id: [integer],
    content: "[text]",
    workspace_id: [integer],
    user_id: [integer],
    created_at: "[DateTime]", 
    updated_at: "[DateTime]",
    user: { ... },
    workspace: { ... }, 
    comments:[],
    enrichments: []
}

View a Comment

View a comment

url:
api/comments/[comment_id]
Request Type:
GET
Request:
BLANK
Response:
{
    id: [integer],
    content: "[text]",
    post_id: [integer],
    user_id: [integer],
    user: { ... },
    created_at: "[DateTime]", 
    updated_at: "[DateTime]"
}

Create New Comment

Create a new comment

url:
api/comments
Request Type:
POST
Request:
{
    comment {
    	content: "[text]",
    	post_id: [integer]
    }
}
Response:
{
    id: [integer],
    content: "[text]",
    post_id: [integer],
    user_id: [integer],
    user: { ... },
    created_at: "[DateTime]", 
    updated_at: "[DateTime]"
}

Generate token to embed Honbu

Generates and return a unique token used to authenticate a user accessing Honbu within an embedded iFrame.

url:
api/users/generateToken.json
Request Type:
Get
Request:
BLANK
Response:
{
    embed_token: "[string]"
}

Embed Honbu into your Application

Embedding Honbu into an iFrame inside your own application or website is a breeze.

All you need to do is make a api call to Sign in a user and then make another api call to Generate a token. You can then use the token to build the page as follows.

Note - [stream_id] is optional. When provided Honbu will show this stream as the active stream. Otherwise the users feed will be shown as the default.

Optional - It's possible to customise the look n' feel of Honbu's interface. See the example below on how this can be achieved.

<!DOCTYPE html>
<html>
<head>
   <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
   <script type="text/javascript" src="http://honbu.io/api-endpoint.js"></script>

   <script type="text/javascript">
      $(function() { 
   	  var h = new Honbu(
   	  		     options: {
                 		color: '[HEX Code]',
                     		backgroundColor: '[HEX Code]',
                     		backgroundUrl: '[URL]'
                  	     }
                  	  );
          h.initialise();
       });
   </script>

</head>
<body>
	<div data-honbu-channel="[stream_id]" data-honbu-token="[embed_token]"></div>   
</body>
</html>

Authenticating Requests

The REST API uses the standard HTTP Authorization header to pass the "auth_token" (recieved from the response of the Sign in a User call). In the syntax of:

Authorization Basic [auth_token]:X

The [auth_token]:X must be wrapped around a Base64 encoding call. The 'X' is just a dummy value for the password which will be ignored. However, it must be include nonetheless.

An example below outlines how to apply authentication to all JavaScript jQuery ajax request. Hopefully, this gives you enough information to apply the same concept to your language of choice.

$.ajaxSetup({
    beforeSend: function(xhr) {
        xhr.setRequestHeader('Authorization', 'Basic ' + btoa([auth_token] + ":X"));
    }
});