Magellan is a project mainly written in JAVASCRIPT and RUBY, it's free.
An API explorer sample app built on Rails 3.
Explore those APIs with the famous Ferdinand Magellan.
Magellan is a customizable API console written in Rails 3. It provides an interface to test/explore any API (see Caveats) by defining the API endpoints and the required parameters for those endpoints. You can submit data to your endpoints, then inspect your outgoing request and the response received.
I noticed a lot of API console being rolled out with the latest API revisions of a few popular sites (Twitter console, Gowalla console) and I wanted to mess around with the idea of creating an API console that would work for any API. Magellan was also highly influenced by hurl.it, created by Chris Wanstrath and Leah Culver for the 2009 Rails Rumble. The project started out initially as just an experiment to see what could be accomplished in a weekend and ended up being used internally on a couple internal projects with one of my current employers.
Magellan makes no attempt at trying to please your eyes. I have added some simple styling to organize the content, but any beautification is left up to you!
I have a live, running instance of the latest version up on Heroku which is preconfigured to hit a few Twitter API endpoints (including updating the status of my test user @ferd_magellan). The link below is the explore interface only. Every other page is protected to prevent tampering with the demo setup.
Amazon EC2 Instance
Currently the response data displayed on the page is somewhat borked. I recently updated to the latest version of the Albino gem (used for syntax highlighting the response) and it appears there might be a bug or two in the gem with the current version. I will have this resolved once I get some feedback on the issue.
Install xmllint (used to format the XML output)
OS X - MacPorts
$ port install libxml2
OS X - Homebrew
$ brew install xmllint
Ubuntu/Debian
$ apt-get install libxml2-utilsPython eggs for pygments (used by the Albino gem) and simplejson (formatting)
$ easy_install pygments simplejsonUpdate gems
$ bundleSetup the database
$ rake db:migrateStart the server
$ rails serverNavigate to http://localhost:3000/setup to start the configuration setup.
Initially, you will need to setup up some authentications. Both HTTP Basic and OAuth 1.0 are currently supported with OAuth2 coming soon. You can setup as many authentications as you want, but you must setup at least one default. When actually testing out the setup APIs, you will be able to toggle between which authentication you want to use for that request.
After creating at least one default authentication, you can setup any global parameters you plan on using across all your API requests. Both standard and header global parameters are ALWAYS sent. Global URL parameters are only sent if the endpoint URL specifies that parameter is needed (more on this below).
A common use for such global parameters is sending along your API key with every request you make. Many services use this to track your usage and moderate abuse. Another example is specifying the response format for all responses from the API.
Normal name/value pairs used in the query string of the request.
Name: q, Value: Stewie Griffin
http://api.example.com/users/search?q=Stewie+Griffin
Header parameters are name/value pairs added to the request headers.
X-Example-Key: k3mm983knmr2msi3inmsnmm299xma3m9x
URL paramters are those used to replace URL "placeholders" specified in the endpoint URL. The placeholder is always prefixed with a colon.
Example URL: http://api.example.com/users/:username.json
In this example, 'username' is the placeholder that you will need to create either a global parameter for, or you can specify an endpoint parameter that will only be used for that specific instance.
In these final steps, you can define groupings for your endpoints and multiple parameter sets per endpoint.
Groups are a way of organizing endpoints. Example groups used for the Twitter API are: 'Timeline, 'Users', 'Direct Messages', etc.
Within each group, you can define as many endpoints as needed. An endpoint is composed of a name, description, and the URL the request will hit. Remember to include any URL parameter placeholders when specifying the endpoint URL.
For each endpoint, you can define multiple sets of parameters you would like to send to the endpoint. Each of these parameter sets can also specify a different HTTP verb (GET, POST, PUT, DELETE). For the most part, a single parameter set per endpoint is all that is required. In this case, just give the parameter set the same name as the endpoint to keep things simple. Below are just two example parameter sets for the same endpoint.
GET with screen_name = roxy, count = 20
GET with user_id = 534651, include_rts = true
You can also specify example data and a description for the different elements that are returned in the request response. This allows you to provide some documentation for the response.
Once everything is setup, you can nagivate to Navigate to http://localhost:3000/ to start exploring those API endpoints! You may have already come across this interface while testing our your endpoint parameter sets.
If you wish to expose your Magellan setup to the public, I highly recommend you enable HTTP Basic access to everything but the explore interface. To do this, simply follow the instructions in the provided ApplicationController. It is setup by default to require authentication for everything but Endpoints#show.
Many thanks for Chris Wanstrath and Leah Culver for their work on hurl.it which this project has been influenced by.