You've found the source code for the RadBus Web API!
To learn more about RadBus, check out: http://dev.radbus.io
In order to contribute or at least play with the code and see how RadBus works under the hood, you need to set up your own development environment.
NOTES:
- These instructions assume you already have a GitHub account and have Git set up on your local machine.
- These instructions are for Mac OS. There's no reason why RadBus wouldn't run on Linux or Windows since it's just a Node.js app. We can create instructions for other OS's as needed down the road.
Here are the steps:
-
If you haven't already, install Node.js
-
If you haven't already, sign up for a free Heroku account and install the Heroku Toolbelt
NOTE: Technically Heroku is not required to run RadBus locally. However, it makes setting up your dev environment a lot easier. Plus if you'd like to push your version of RadBus to the cloud (for free), you've got an easy option. It's also the hosting environment for the production RadBus API!
- Fork this repo and clone it down to your local machine:
$ git clone git@github.com:<your-git-username>/radbus-api.git
- Install Node.js dependencies:
$ npm install
-
Capture the environment variables used by RadBus in a local
.env
file, which will be read byforeman
, the tool we'll use to run the app locally:echo 'RADBUS_FUTURE_MINUTES=60' >> .env echo 'RADBUS_TIMEZONE=America/Chicago' >> .env # get the following values from the JSON returned by https://api.radbus.io/v1/oauth2 echo 'RADBUS_GOOGLE_API_AUTH_SCOPES=value' >> .env echo 'RADBUS_GOOGLE_API_CLIENT_ID=value' >> .env echo 'RADBUS_GOOGLE_API_CLIENT_SECRET=value' >> .env # the salt value can be anything you want it to be echo 'RADBUS_USER_ID_SALT=use-the-force' >> .env # enable/disable API Keys echo 'API_KEYS_ENABLED=true' >> .env # comma-separated list of API keys. These can be anything you want it to be # If API_KEYS is enabled, all API requests must contain one of these keys echo 'API_KEYS=rad,bus,1234' >> .env
-
Create a MongoDB database used by the API to store user schedules. This is where Heroku helps a ton. While you could install and run MongoDB locally or go out and fire up a free cloud-based instance somewhere, the following steps in Heroku will set it up in minutes using MongoHQ, one of their add-on partners:
-
If you haven't done so already, log into Heroku:
$ heroku login
NOTE: If Heroku reports that you don't have an existing public key and asks if you'd like to create one, answer yes!
-
Create a new Heroku app:
$ heroku create
You'll see output that looks something like this:
Creating warm-sierra-1964... done, stack is cedar http://warm-sierra-1964.herokuapp.com/ | git@heroku.com:warm-sierra-1964.git Git remote heroku added
If that was the output of your app, your app's URL would be:
http://warm-sierra-1964.herokuapp.com/
NOTE: You won't have to deploy your code to this app if you don't want to. However, we're going to the add-ons that we register with it to power your local dev environment.
-
Add the free MongoHQ database "Sandbox" add-on:
$ heroku addons:add mongohq
-
Get the value of the
MONGOHQ_URL
environment variable of the MongoDB database created by that add-on:$ heroku config
-
Capture that in our
.env
file:# value is from the heroku config command output echo 'MONGOHQ_URL=value' >> .env
-
Try running all the tests to make sure they pass on your machine:
$ npm test
- Start the local app:
$ foreman start
NOTE: By default foreman
runs on port 5000.
- In a different Terminal window, try hitting the version 1 Root resource:
$ curl http://localhost:5000/v1 | python -m json.tool
You should get output that looks something like this:
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 77 100 77 0 0 24421 0 --:--:-- --:--:-- --:--:-- 25666
{
"api_version": "1.0.0",
"app_version": "0.3.2",
"service_name": "RadBus Web API"
}
That's it!
If you make some changes, commit them to your local repo, and would like to push them up to your Heroku account for all to see, all you have to do is:
$ git push heroku master
If you browse to the base URL of your app, you will get automatically redirected (302) to the REST API Documentation site. Try hitting one of the other resources instead. For example:
$ curl https://warm-sierra-1964.herokuapp.com/v1 | python -m json.tool
NOTE: The RadBus API requires SSL unless running on localhost
. Be sure to use https://
URL's with your REST clients to avoid getting a 301 response.
Per the REST Documentation in order to access many of the API's resources, you need to pass an OAuth2 token so it can identify you and look up your schedule. Having a valid token on hand is often necessary when developing, but it can be a little tricky. This section exists to provide some easy techniques to do so.
The easiest method to obtain an actual valid token is using the RadBus website since it will be your user token and will have an actual schedule associated with it (assuming you've already set one up). Here's how:
- Open a new window in your web browser. In this example we will be using the Google Chrome browser, but any browser will do as long as you know how to view it's HTTP traffic.
- Open Developer Tools (Menu > Tools > Developers Tools).
- Click on the Network tab.
- Browse to the RadBus website.
- Several network calls should show up in the Developer Tools pane. You're looking for one close to the bottom of the list that represents an AJAX
GET
call to either the Schedule resource or the Departures resource since both of those require authentication. For example a call to Schedule will have the following attributes:
Name/Path | Method | Status/Text | Type | Initiator |
---|---|---|---|---|
schedule / api.radbus.io/v1 |
GET |
200 / OK |
application\json |
Other |
- Select that call and then make sure the Headers tab is selected.
- Under the Request Headers section you should see a header called
Authorization
. Select and copy its entire value, including the prefixingBearer
.
You now have a valid token! However, this one will only last for an hour, so as you're developing it may expire and you'll have to perform the above process again to get a new one.
If you are running your own radbus-api server and have the API_KEYS_ENABLED flag enabled:
API_KEYS_ENABLED=true
API_KEYS=rad,bus,1234
You will need to include an api-key header in all api requests. Here is an example using curl:
$ curl --header "api-key: 1234" http://localhost:5001/v1/routes
Note that for authorized requests you will also need to include the OAuth token provided from the OAuth2 provider. Here is an example of an authorized request with the API_KEYS_ENABLED flag enabled:
$ curl -H "api-key: 1234" -H "Authorization: Bearer AbCdEf123456" http://localhost:5001/v1/departures