Try it now

Watch this screencast describing how to install ApiAxle by running through the below instructions.

If you would like us to do this for you then get in touch.

Prerequisites

Base system

There are some base libraries you will need on a fresh install. Ubuntu users might want to make sure the following has been run:

$ sudo apt-get install python-software-properties \
        build-essential \
        libxml2-dev

Node.js

Only versions 0.10 and above are supported. Here’s the official documentation.

Ubuntu users can use this PPA. Which would have you do the following:

$ sudo add-apt-repository ppa:chris-lea/node.js
$ sudo apt-get update
$ sudo apt-get install nodejs

Redis

Redis is an advanced key/value store. It’s where ApiAxle stores its data. Find the installation instructions on redis.io. Ubuntu users:

$ sudo apt-get install redis-server

ApiAxle

With the above finished you should just be able to do this:

$ sudo npm install -g apiaxle-repl \
       apiaxle-proxy \
       apiaxle-api

Now those commands exist in your PATH.

Trying it with your API

Lets say you want to put your brand new AcmeApi (running at localhost:5000) behind a proxy. Here’s how you might do it:

Start the proxy service with this command:

$ apiaxle-proxy -f 1 -p 3000 -q

It’ll now listen on port 3000, fork once (-f 1) and will process it’s own events (thanks to -q, more on that below). If you now hit http://localhost:3000/ you’ll get an ApiUnknown error message. That’s because ApiAxle decides which API you want to use via subdomains. Put this line in your /etc/hosts file:

127.0.0.1 acme.api.localhost

Now when you hit http://acme.api.localhost:3000/ you’ll see the same error but with a slightly different message. That’s because ApiAxle doesn’t know how to call acme. Open the apiaxle repl:

$ apiaxle

and then run these commands:

axle> api "acme" create endPoint="localhost:5000"

Now create and link an API key:

axle> key "1234" create
axle> api acme linkkey "1234"

Now try calling the graph API with any of the options you know it accepts. Here’s an example that will print our my information:

$ curl 'http://acme.api.localhost:3000/users?api_key=1234'

Try it without the key and you’ll get an error. If you try to hit the API more that twice a second you’ll get a Qps error.

Under the hood this has been translated to graph.acme.com/users.

The event processor

apiaxle-proxy ships with a tool called apiaxle-proxy-event-processor which, assuming you haven’t started the proxy itself with the -q parameter, will listen out for hits and errors from the proxy and process them in a separate process. This makes scaling much easier as the bulk of the work happens when processing statistics.

Moving past the testing

You can now tell nginx to pass through the Host header to represent your API like this:

# put as many Axle instances in here as you like
upstream apiaxle_cluster {
  server 127.0.0.1:3000;
  server 127.0.0.1:3001;
  server 127.0.0.1:3002;
  server 127.0.0.1:3003;
}

server {
  listen 80;
  server_name api.acme.com;

  location / {
    proxy_pass http://apiaxle_cluster;
    proxy_set_header Host "acme.api.localhost";
  }
}

Have a look in this directory for some Nginx and supervisord example configuration which are production suitable.