Baruwa API

The Baruwa API allows you to manage a Baruwa Server in a programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions. The Baruwa API is organized around REST and uses OAUTH 2.0 authentication. It is therefore possible to use off-the-shelf HTTP clients in any programming language.

Most of the functionality that you are familiar with in the Baruwa web interface is also available through the API, allowing you to script the complex actions that your situation requires.

How Baruwa uses OAuth 2.0

OAuth is an industry-standard open standard for authorization used by many companies to provide secure access to protected resources. The Baruwa API uses the OAuth 2.0 protocol to authorize requests.

Here is an overview of how the OAuth 2.0 auth flow works:

../_images/baruwa_oauth.png

Application registration

Register your application by logging into the Baruwa web interface, and by going to the API & Applications menu under the user account.

When you create a new application, Baruwa generates a set of OAuth keys for the application (the keys consist of a client_id and client_secret).

Access token requests

You then obtain an access token for your application by sending a request to the /api/v1/oauth/token endpoint. You need to authenticate your access token request with your application credentials obtained as described above.

The Baruwa server, acting as the authorization server, verifies your application credentials and returns Bearer and Refresh access tokens.

API request authentication

When you make the API calls, make request by adding the access token in the Authorization header using the following syntax:

Authorization: {tokenType} {accessToken}

Example:

Authorization: Bearer XXXXXX...XXXXX9X2

Documentation

The Baruwa API documentation is available online.

API Libraries

Python

Available through pip:

pip install BaruwaAPI

If your system doesn’t have pip, you can also use easy_install:

easy_install BaruwaAPI

The source code is in the Github BaruwaAPI repo and the package is available on PyPI

Ruby

Available as a gem:

gem install baruwa

If you use bundler, add the following line:

gem 'baruwa'

The source code is in the Github baruwa-ruby repo and the package is available on rubygems.org

Perl

Available as a cpan package:

cpan Net::BaruwaAPI

The source code is in the Github Net-BaruwaAPI repo and the package is available on cpan

Golang

Available as an API library and a commandline tool