Getting Started
Installation¶
Installing From Binary Packages¶
Debian 9 (Stretch)
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 367404D553B42995
$ echo "deb http://dl.bintray.com/nrel/api-umbrella-debian stretch main" | sudo tee /etc/apt/sources.list.d/api-umbrella.list
$ sudo apt-get update
$ sudo apt-get install api-umbrella
Debian 8 (Jessie)
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 367404D553B42995
$ echo "deb http://dl.bintray.com/nrel/api-umbrella-debian jessie main" | sudo tee /etc/apt/sources.list.d/api-umbrella.list
$ sudo apt-get update
$ sudo apt-get install api-umbrella
Enterprise Linux 7 (CentOS/RedHat/Oracle/Scientific Linux)
$ curl https://bintray.com/nrel/api-umbrella-el7/rpm | sudo tee /etc/yum.repos.d/api-umbrella.repo
$ sudo yum install api-umbrella
Enterprise Linux 6 (CentOS/RedHat/Oracle/Scientific Linux)
$ curl https://bintray.com/nrel/api-umbrella-el6/rpm | sudo tee /etc/yum.repos.d/api-umbrella.repo
$ sudo yum install api-umbrella
Ubuntu 18.04 (Bionic)
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 367404D553B42995
$ echo "deb http://dl.bintray.com/nrel/api-umbrella-ubuntu bionic main" | sudo tee /etc/apt/sources.list.d/api-umbrella.list
$ sudo apt-get update
$ sudo apt-get install api-umbrella
Ubuntu 16.04 (Xenial)
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 367404D553B42995
$ echo "deb http://dl.bintray.com/nrel/api-umbrella-ubuntu xenial main" | sudo tee /etc/apt/sources.list.d/api-umbrella.list
$ sudo apt-get update
$ sudo apt-get install api-umbrella
Installing With Chef¶
If you use Chef for managing your servers, we provide a cookbook that can be used to install the binary packages and configure API Umbrella.
Running With Docker¶
In this simple example, custom API Umbrella configuration can be defined in the config/api-umbrella.yml
file on host machine. This gets mounted as /etc/api-umbrella/api-umbrella.yml
inside the container, which is the path for the configuration file the rest of the documentation will reference.
$ mkdir config && touch config/api-umbrella.yml
$ docker run -d --name=api-umbrella -p 80:80 -p 443:443 -v "$(pwd)/config":/etc/api-umbrella nrel/api-umbrella
Installing From Source Code¶
Installing from a binary package is recommended, if available (let us know if you’d like to see binary packages for other platforms). However, if a binary package is not available you can compile from source.
Setup¶
Start API Umbrella:
$ sudo /etc/init.d/api-umbrella start
Browse to your server’s hostname. You should land on the default homepage:
Default API Umbrella homepage
Congrats! You’re now up and running with API Umbrella. There are a variety of things you can do to start using the platform. Read on for a quick tutorial:
Quick Tutorial¶
Login to the web admin¶
A web admin is available to perform basic tasks:
https://your-api-umbrella-host/admin/
The very first time you access the admin, you’ll be given a chance to create your first admin account.
Add API Backends¶
Out of the box, API Umbrella doesn’t know about any APIs. You must first configure the API backends that will be proxied to.
In this example, we’ll proxy to Google’s Geocoding API (but you’ll more likely be proxying to your own web services).
Step 1: Login to the web admin and navigate to the “API Backends” section under the “Configuration” menu.
Step 2: Add a new backend:
Add API Backend Example
Step 3: Navigate to the “Publish Changes” page under the “Configuration” menu and press the Publish button.
Google’s API should now be available through the API Umbrella proxy.
Signup for an API key¶
On your local environment, visit the signup form:
https://your-api-umbrella-host/signup/
Signup to receive your own unique API key for your development environment.
Make an API request¶
Assuming you added the Google Geocoding example as an API backend, you should now be able to make a request to Google’s Geocoding API proxied through your local API Umbrella instance:
http://your-api-umbrella-host/google/maps/api/geocode/json?address=Golden,+CO&sensor=false&api_key=**YOUR_KEY_HERE**
You can see how API Umbrella layers its authentication on top of existing APIs by making a request using an invalid key:
http://your-api-umbrella-host/google/maps/api/geocode/json?address=Golden,+CO&sensor=false&api_key=INVALID_KEY