A client library for HaveAPI based APIs in JavaScript.
- Manual - Copy
dist/haveapi-client.jsto your project - Node.js -
npm install haveapi-client - bower -
bower install haveapi-client
On the web:
<script src="haveapi-client.js"></script>With NodeJS:
var HaveAPI = require('haveapi-client');Create a client instance:
var api = new HaveAPI.Client("http://your.api.tld");Before the client can be used, it must be set up:
api.setup(function() {
console.log("The client is ready to roll");
});haveapi-client-js supports HTTP basic and token authentication. However, the HTTP basic method is by default not allowed by HaveAPI to be used from web browsers.
api.setup(function() {
console.log("The client is ready to roll");
api.authenticate('basic', {
user: 'yourname',
password: 'yourpassword'
}, function(c, status) {
console.log("Are we authenticated?", status);
});
});Request a token:
api.setup(function() {
console.log("The client is ready to roll");
api.authenticate('token', {
user: 'yourname',
password: 'yourpassword'
}, function(c, status) {
console.log("Are we authenticated?", status);
console.log("Auth token is:", api.authProvider.token);
});
});Use an existing token:
api.setup(function() {
console.log("The client is ready to roll");
api.authenticate('token', {
token: 'qwertyuiopasdfghjkl',
}, function(c, status) {
console.log("Are we authenticated?", status);
});
});It is possible to avoid calling setup and use only authenticate, if you won't use the client before authentication anyway.
api.authenticate('token', {
token: 'qwertyuiopasdfghjkl',
}, function(c, status) {
console.log("The client is set up");
console.log("Are we authenticated?", status);
});The token authentication also supports multi-factor authentication, i.e. the API server may require clients to call multiple authentication actions with different credentials. It is necessary to implement a callback function which is called when additional authentication steps are needed. The function either returns input parameters to use for authentication, or invokes the callback which it gets as an argument.
api.authenticate('token', {
user: 'yourname',
password: 'yourpassword',
callback: function (action, params, cont) {
console.log("The server requires additional authentication", action);
// Either call the callback whenever ready
cont({"code": 123456});
// Or return the parameters immediately
return {"code": 123456};
}
}, function(c, status) {
console.log("Are we authenticated?", status);
console.log("Auth token is:", api.authProvider.token);
});Resources and actions can be used only after the client has been set up or authenticated.
// Get a resource
api.vps.show(101, function(c, vps) {
console.log("Received VPS:", vps.id, vps.hostname);
});
// Create a resource
api.vps.create(101, {
hostname: 'something',
and: 'others'
}, function(c, reply) {
console.log('Created VPS?', reply.isOk());
});
// It's also possible to create it with an empty instance
var myvps = api.vps.new();
myvps.hostname = 'something_different';
myvps.save(function(c, vps) {
console.log('created a vps?', vps.isOk(), vps.id);
});
// Lists of objects
api.vps.list({limit: 10}, function(c, vpses) {
console.log('received a list of vpses', vpses.isOk(), vpses.length);
vpses.each(function(vps) {
console.log('containing', vps.id, vps.hostname);
});
});HaveAPI has support for long-running actions. Progress of such actions can be monitored. The client has a callback to get updates about the action's state and a callback that is called when the action is finished.
Notice that the callbacks are passed in a different way, see the documentation to learn more about it.
api.vps.restart(101, {
// onReply is called when the API server responds. It is the final callback
// for non-blocking actions.
onReply: function (c, reply) {
console.log('Server replied, action is being executed');
},
// Called regularly when the action's state changes
onStateChange: function (c, reply, state) {
console.log('Current progress:', state.progress.toString());
},
// Called when the action finishes
onDone: function (c, reply) {
console.log('Action done!');
}
})Some actions can be cancelled from the onStateChange callback if
state.canCancel is true.
...
onStateChange: function (c, reply, state) {
if (state.canCancel) {
// Note that the cancel operation can also be blocking. That depends on the
// API server.
state.cancel({
onReply: function () { ... },
onStateChange: function () { ... },
onDone: function () { ... }
});
}
}
...Metadata may be used to prefetch associated resources or get total item count.
api.vps.list({
limit: 10,
meta: {count: true, includes: 'user,node__location'}
}, function(c, vpses) {
console.log('received a list of vpses', vpses.isOk());
console.log('number of received vpses', vpses.length);
console.log('total count of vpses', vpses.tocalCount)
vpses.each(function(vps) {
// Associations user, node and node__location are prefetched.
// They can be accessed immediately without any additional
// HTTP request.
console.log('VPS', vps.id, vps.hostname, vps.user.login, vps.node.name, vps.node.location.label);
});
});Sometimes it is needed to use the client independently on multiple places, but to only have one instance and setup/authenticate just once.
There are two hooks available: setup and authenticated. They are both called
after the event occurs. A hook may be registered multiple times and it does not matter
if it is registered before (the callback is queued) or after (it is called right away)
the event actually happens.
// The client is initialized, set up and authenticated somewhere else in the
// code. Something just needs to be done when it is ready.
api.after('setup', function() {
console.log("The client is set up");
});
api.after('authenticated', function() {
console.log("The client is authenticated");
})https://projects.vpsfree.cz/haveapi-client-js/ref/
haveapi-client-js is released under the MIT license.