About

Rack::Stereoscope - unobtrusively add an interactive, explorable HTML interface to your RESTful API. Use it to manually test your API from a browser. Use it to make your API self-documenting. Use it to quickly prototype new API features and get a visual feel for the data structures...

Details

Rack::Stereoscope - bringing a new dimension to your RESTful API

Stereoscope is inspired by the idea that software should be explorable. Put stereoscope in front of your RESTful API, and you get an interactive, explorable HTML interface to your API for free. Use it to manually test your API from a browser. Use it to make your API self-documenting. Use it to quickly prototype new API features and get a visual feel for the data structures.

Stereoscope is designed to be unobtrusive. It will not interpose itself unless the request asks for HTML (i.e. it comes from a browser). If the request requests no explicit content type; or if it requests a content-type other than HTML, Stereoscope stays out of the way.

This middleware is especially well-suited to presenting APIs that are heavily hyperlinked (and if your API doesn't have hyperlinks, why not?). Stereoscope does it's best to recognize URLs and make them clickable. What's more, Stereoscope supports URI Templates. If your data includes URL templates such as the following:

http://example.org/{foo}?bar={bar}

Stereoscope will render a form which enables the user to experiment with different expansions of the URI template.

Limitations:

• Currently only supports JSON data
• Only link-ifies fully-qualified URLs; relative URLs are not supported
• Read-only exploration; no support for POSTs, PUTs, or DELETEs.

Usage

1. Install the prerequsites:

    gem install marakaby json nokogiri mynyml-rack-accept-media-types addressable
   

2. Put it in your rackup file:

    require 'rack_stereoscope'
    use Rack::Stereoscope;
   

3. Start your app, point your browser at it, and start exploring!