restapi 0.0.1

data/spec/dummy/Rakefile

@@ -0,0 +1,7 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+require 'rake'
+
+Dummy::Application.load_tasks

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/spec/dummy/app/controllers/dogs_controller.rb

@@ -0,0 +1,22 @@
+class DogsController < ApplicationController
+  
+  api :desc => "Show dogs profile",
+      :path => "/dogs/:id",
+      :method => "GET"
+  error :code => 401, :desc => "Unauthorized"
+  error :code => 404, :desc => "Not Found"
+  desc "+Show dog+ This is *description* of dog show method."
+  def show
+    render :nothing => true
+  end
+  
+  #############################################################################
+
+  api :desc => "List all dogs",
+      :path => "/dogs",
+      :method => "GET"
+  desc "List all dogs which are registered on our social site."
+  def index
+    render :text => "List of dogs"
+  end
+end

data/spec/dummy/app/controllers/twitter_example_controller.rb

@@ -0,0 +1,306 @@
+class TwitterExampleController < ApplicationController
+  
+  resource_description do
+    name 'Users'
+    short_description 'Users are at the center of everything Twitter: they follow, they favorite, and tweet & retweet.'
+    path '/users/'
+  end
+  
+  api :desc => 'Return up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two.',
+      :path => '/users/lookup',
+      :method => 'GET'
+  param :screen_name, String, :desc => 'A comma separated list of screen names, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger (up to 100 screen names) requests.'
+  param :user_id, Integer, :desc => 'A comma separated list of user IDs, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger requests.'
+  param :include_entities, String, :desc => 'When set to either <code>true</code>, <code>t</code> or <code>1</code>, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
+  
+  description <<-EOS
+    Return up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two. The author's most recent status (if the authenticating user has permission) will be returned inline.
+
+    This method is crucial for consumers of the {Streaming API}[link:https://dev.twitter.com/pages/streaming_api]. It's also well suited for use in tandem with friends/ids[link:https://dev.twitter.com/doc/get/friends/ids] and followers/ids[link:https://dev.twitter.com/doc/get/followers/ids].
+    
+    === Extended description
+    There are a few things to note when using this method.
+
+    * You must be following a protected user to be able to see their most recent status update. If you don't follow a protected user their status will be removed.
+    * The order of user IDs or screen names may not match the order of users in the returned array.
+    * If a requested user is unknown, suspended, or deleted, then that user will not be returned in the results list.
+    * You are strongly encouraged to use a POST for larger requests.
+  EOS
+  def lookup
+    render :text => "lookup"
+  end
+  
+  api :desc => 'Access the profile image in various sizes for the user with the indicated screen_name.',
+      :path => '/users/profile_image/:screen_name',
+      :method => 'GET'
+  param :screen_name, String, :required => true, :desc => 'The screen name of the user for whom to return results for. Helpful for disambiguating when a valid screen name is also a user ID.'
+  param :size, ['bigger','normal','mini','original'], :desc => <<-EOS
+    Specifies the size of image to fetch. Not specifying a size will give the default, normal size of 48px by 48px. Valid options include:
+
+    * bigger - 73px by 73px
+    * normal - 48px by 48px
+    * mini - 24px by 24px
+    * original - undefined. This will be the size the image was originally uploaded in. The filesize of original images can be very big so use this parameter with caution.
+  EOS
+  description <<-EOS
+    Access the profile image in various sizes for the user with the indicated screen_name. If no size is provided the normal image is returned.
+
+    This resource does not return JSON or XML, but instead returns a 302 redirect to the actual image resource.
+
+    This method should only be used by application developers to lookup or check the profile image URL for a user. This method must not be used as the image source URL presented to users of your application.
+  EOS
+  def profile_image
+    render :text => "profile_image"
+  end
+  
+  api :path => '/users/search', :method => 'GET',
+      :desc => 'Runs a search for users similar to Find People button on Twitter.com.'
+  param :q, String, :desc => 'The search query to run against people search.', :required => true
+  param :page, Integer, :desc => 'Specifies the page of results to retrieve.'
+  param :per_page, Integer, :desc => 'The number of people to retrieve. Maxiumum of 20 allowed per page.'
+  param :include_entities, String, :desc => 'When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.'
+  description <<-EOS
+    Runs a search for users similar to Find People button on Twitter.com. The results returned by people search on Twitter.com are the same as those returned by this API request. Note that unlike GET search, this method does not support any operators.
+
+    Only the first 1000 matches are available.
+    
+    === Extended description
+    This method has a feature-specific rate limit of 60 calls per hour that is applied in conjunction with the main REST API rate limit. Calls to this method will count against the feature-specific rate limit and the main REST API rate limit. If either limit is exhausted, the request will fail. You can monitor the status of the feature-specific rate limit by inspecting the HTTP response headers <tt>X-FeatureRateLimit-Limit</tt>, <tt>X-FeatureRateLimit-Remaining</tt>, and <tt>X-FeatureRateLimit-Reset</tt>. These headers correspond to the <tt>X-RateLimit</tt> headers provided by the main REST API limit.
+      [
+        {
+          "name": "Twitter API",
+          "profile_sidebar_border_color": "87bc44",
+          "profile_background_tile": false,
+          "profile_sidebar_fill_color": "e0ff92",
+          "location": "San Francisco, CA",
+          "profile_image_url": "http://a3.twimg.com/profile_images/689684365/api_normal.png",
+          "created_at": "Wed May 23 06:01:13 +0000 2007",
+          "profile_link_color": "0000ff",
+          "favourites_count": 2,
+          "url": "http://apiwiki.twitter.com",
+          "contributors_enabled": true,
+          "utc_offset": -28800,
+          "id": 6253282,
+          "profile_use_background_image": true,
+          "profile_text_color": "000000",
+          "protected": false,
+          "followers_count": 160753,
+          "lang": "en",
+          "verified": true,
+          "profile_background_color": "c1dfee",
+          "geo_enabled": true,
+          "notifications": null,
+          "description": "The Real Twitter API. I tweet about API changes, service issues and happily answer questions about Twitter and our API. Don't get an answer? It's on my website.",
+          "time_zone": "Pacific Time (US & Canada)",
+          "friends_count": 19,
+          "statuses_count": 1858,
+          "profile_background_image_url": "http://a3.twimg.com/profile_background_images/59931895/twitterapi-background-new.png",
+          "status": {
+            "coordinates": null,
+            "favorited": false,
+            "created_at": "Tue Jun 22 16:53:28 +0000 2010",
+            "truncated": false,
+            "text": "@Demonicpagan possible some part of your signature generation is incorrect & fails for real reasons.. follow up on the list if you suspect",
+            "contributors": null,
+            "id": 16783999399,
+            "geo": null,
+            "in_reply_to_user_id": 6339722,
+            "place": null,
+            "source": "<a href="http://www.tweetdeck.com" rel="nofollow">TweetDeck</a>",
+            "in_reply_to_screen_name": "Demonicpagan",
+            "in_reply_to_status_id": 16781827477
+          },
+          "screen_name": "twitterapi",
+          "following": null
+        },
+        ...
+        {
+          "name": "twitterAPI",
+          "profile_sidebar_border_color": "87bc44",
+          "profile_background_tile": false,
+          "profile_sidebar_fill_color": "e0ff92",
+          "location": null,
+          "profile_image_url": "http://s.twimg.com/a/1277162817/images/default_profile_6_normal.png",
+          "created_at": "Fri Jun 04 12:07:25 +0000 2010",
+          "profile_link_color": "0000ff",
+          "favourites_count": 0,
+          "url": null,
+          "contributors_enabled": false,
+          "utc_offset": null,
+          "id": 151851125,
+          "profile_use_background_image": true,
+          "profile_text_color": "000000",
+          "protected": false,
+          "followers_count": 0,
+          "lang": "ja",
+          "verified": false,
+          "profile_background_color": "9ae4e8",
+          "geo_enabled": false,
+          "notifications": false,
+          "description": null,
+          "time_zone": null,
+          "friends_count": 0,
+          "statuses_count": 0,
+          "profile_background_image_url": "http://s.twimg.com/a/1277162817/images/themes/theme1/bg.png",
+          "screen_name": "popoAPI",
+          "following": false
+        }
+      ]
+  EOS
+  def search
+    render :text => 'search'
+  end
+  
+  api :path => '/users/show', :method => 'GET',
+      :desc => 'Returns extended information of a given user, specified by ID or screen name as per the required id parameter.'
+  param :user_id, Integer, :required => true, :desc => <<-EOS
+    The ID of the user for whom to return results for. Either an id or screen_name is required for this method.
+    _Note_: Specifies the ID of the user to befriend. Helpful for disambiguating when a valid user ID is also a valid screen name.
+  EOS
+  param :screen_name, String, :desc => 'The screen name of the user for whom to return results for. Either a id or screen_name is required for this method.'
+  description <<-EDOC
+    Returns extended information of a given user, specified by ID or screen name as per the required id parameter. The author's most recent status will be returned inline.
+    
+    You must be following a protected user to be able to see their most recent status update. If you don't follow a protected user, or request this method without autenticating, the users status will be removed.
+
+    The URL pattern <tt>/version/users/show/:screen_name_or_user_id.format</tt> is still accepted but not recommended. As a sequence of numbers is a valid screen name we recommend using the +screen_name+ or +user_id+ parameter instead.
+  EDOC
+  def show
+    render :text => 'show'
+  end
+  
+  api :path => '/users/contributors', :method => 'GET',
+      :description => 'Returns an array of users who can contribute to the specified account.'
+  param :user_id, Integer, :desc => 'The ID of the user for whom to return results for. Helpful for disambiguating when a valid user ID is also a valid screen name.'
+  param :screen_name, String, :desc => 'The screen name of the user for whom to return results for. Helpful for disambiguating when a valid screen name is also a user ID.'
+  param :include_entities, String
+  param :skip_status, ['t','true','1'],
+    :description => 'When set to either true, t or 1 statuses will not be included in the returned user objects.'
+    
+  description <<-EDOC
+    === Example request
+    GET	https://api.twitter.com/1/users/contributors.json?screen_name=twitterapi&include_entities=true&skip_status=true
+      [
+        {
+          "profile_sidebar_border_color": "C0DEED",
+          "profile_background_tile": false,
+          "name": "Matt Harris",
+          "profile_sidebar_fill_color": "DDEEF6",
+          "expanded_url": "http://themattharris.com",
+          "created_at": "Sat Feb 17 20:49:54 +0000 2007",
+          "location": "SFO/LHR/YVR/JAX/IAD/AUS",
+          "profile_image_url": "http://a1.twimg.com/profile_images/554181350/matt_normal.jpg",
+          "follow_request_sent": false,
+          "is_translator": false,
+          "profile_link_color": "0084B4",
+          "id_str": "777925",
+          "entities": {
+            "urls": [
+
+            ],
+            "hashtags": [
+
+            ],
+            "user_mentions": [
+              {
+                "name": "Cindy Li",
+                "id_str": "29733",
+                "id": 29733,
+                "indices": [
+                  45,
+                  53
+                ],
+                "screen_name": "cindyli"
+              }
+            ]
+          },
+          "default_profile": true,
+          "url": "http://t.co/292MnqA",
+          "contributors_enabled": false,
+          "favourites_count": 120,
+          "id": 777925,
+          "utc_offset": -28800,
+          "listed_count": 271,
+          "profile_use_background_image": true,
+          "followers_count": 6242,
+          "lang": "en",
+          "protected": false,
+          "profile_text_color": "333333",
+          "profile_background_color": "C0DEED",
+          "time_zone": "Pacific Time (US & Canada)",
+          "geo_enabled": true,
+          "description": "Developer Advocate at Twitter and married to @cindyli. NASA enthusiast, British expat and all around geek living in San Francisco.",
+          "notifications": false,
+          "verified": false,
+          "profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
+          "statuses_count": 3835,
+          "display_url": "themattharris.com",
+          "friends_count": 360,
+          "default_profile_image": false,
+          "following": false,
+          "show_all_inline_media": false,
+          "screen_name": "themattharris"
+        },
+        ...
+        {
+          "profile_sidebar_border_color": "547980",
+          "profile_background_tile": true,
+          "name": "Ryan Sarver",
+          "profile_sidebar_fill_color": "F8FCF2",
+          "expanded_url": "http://sarver.org",
+          "created_at": "Mon Feb 26 18:05:55 +0000 2007",
+          "location": "San Francisco, CA",
+          "profile_image_url": "http://a2.twimg.com/profile_images/644997837/ryan_sarver_twitter_big_normal.jpg",
+          "follow_request_sent": false,
+          "is_translator": false,
+          "profile_link_color": "547980",
+          "id_str": "795649",
+          "entities": {
+            "urls": [
+
+            ],
+            "hashtags": [
+
+            ],
+            "user_mentions": [
+
+            ]
+          },
+          "default_profile": false,
+          "contributors_enabled": true,
+          "url": "http://t.co/Lzsetyk",
+          "favourites_count": 246,
+          "id": 795649,
+          "utc_offset": -28800,
+          "profile_use_background_image": true,
+          "listed_count": 1384,
+          "followers_count": 280756,
+          "lang": "en",
+          "protected": false,
+          "profile_text_color": "594F4F",
+          "profile_background_color": "45ADA8",
+          "time_zone": "Pacific Time (US & Canada)",
+          "geo_enabled": true,
+          "description": "platform/api at twitter",
+          "notifications": false,
+          "verified": false,
+          "friends_count": 1022,
+          "profile_background_image_url": "http://a0.twimg.com/profile_background_images/113854313/xa60e82408188860c483d73444d53e21.png",
+          "display_url": "sarver.org",
+          "default_profile_image": false,
+          "statuses_count": 7031,
+          "following": false,
+          "show_all_inline_media": true,
+          "screen_name": "rsarver"
+        }
+      ]
+  EDOC
+  def contributors
+    render :text => 'contributors'
+  end
+  
+  def index
+    render :text => 'twitter example'
+  end
+  
+end

data/spec/dummy/app/controllers/users_controller.rb

@@ -0,0 +1,211 @@
+class UsersController < ApplicationController
+  
+  resource_description do
+    name 'Members'
+    short 'Site members'
+    path '/users'
+    version '1.0 - 3.4.2012'
+    param :id, Fixnum, :desc => "User ID", :required => true
+    description <<-EOS
+      == Long description
+
+      Example resource for rest api documentation
+
+      These can now be accessed in <tt>shared/header</tt> with:
+
+        Headline: <%= headline %>
+        First name: <%= person.first_name %>
+
+      If you need to find out whether a certain local variable has been assigned a value in a particular render call,
+      you need to use the following pattern:
+
+        <% if local_assigns.has_key? :headline %>
+          Headline: <%= headline %>
+        <% end %>
+
+      Testing using <tt>defined? headline</tt> will not work. This is an implementation restriction.
+
+      === Template caching
+
+      By default, Rails will compile each template to a method in order to render it. When you alter a template,
+      Rails will check the file's modification time and recompile it in development mode.
+    EOS
+  end
+  
+  api :short => "Show user profile",
+      :path => "/users/:id",
+      :method => "GET"
+  error :code => 401, :desc => "Unauthorized"
+  error :code => 404, :desc => "Not Found"
+  param :id, Fixnum, :desc => "user id", :required => true
+  param :id, Integer, :desc => "user id", :required => true
+  param :session, String, :desc => "user is logged in", :required => true
+  param :float_param, Float, :desc => "float param"
+  param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
+  param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
+  param :proc_param, lambda { |val| 
+    val == "param value" ? true : "The only good value is 'param value'."
+  }, :desc => "proc validator"
+  description <<-eos
+    = Action View Base
+
+    Action View templates can be written in several ways. If the template file has a <tt>.erb</tt> extension then it uses a mixture of ERb
+    (included in Ruby) and HTML. If the template file has a <tt>.builder</tt> extension then Jim Weirich's Builder::XmlMarkup library is used.
+
+    == ERB
+
+    You trigger ERB by using embeddings such as <% %>, <% -%>, and <%= %>. The <%= %> tag set is used when you want output. Consider the
+    following loop for names:
+
+      <b>Names of all the people</b>
+      <% @people.each do |person| %>
+        Name: <%= person.name %><br/>
+      <% end %>
+
+    The loop is setup in regular embedding tags <% %> and the name is written using the output embedding tag <%= %>. Note that this
+    is not just a usage suggestion. Regular output functions like print or puts won't work with ERB templates. So this would be wrong:
+
+      <%# WRONG %>
+      Hi, Mr. <% puts "Frodo" %>
+
+    If you absolutely must write from within a function use +concat+.
+
+    <%- and -%> suppress leading and trailing whitespace, including the trailing newline, and can be used interchangeably with <% and %>.
+
+    === Using sub templates
+
+    Using sub templates allows you to sidestep tedious replication and extract common display structures in shared templates. The
+    classic example is the use of a header and footer (even though the Action Pack-way would be to use Layouts):
+
+      <%= render "shared/header" %>
+      Something really specific and terrific
+      <%= render "shared/footer" %>
+
+    As you see, we use the output embeddings for the render methods. The render call itself will just return a string holding the
+    result of the rendering. The output embedding writes it to the current template.
+
+    But you don't have to restrict yourself to static includes. Templates can share variables amongst themselves by using instance
+    variables defined using the regular embedding tags. Like this:
+
+      <% @page_title = "A Wonderful Hello" %>
+      <%= render "shared/header" %>
+
+    Now the header can pick up on the <tt>@page_title</tt> variable and use it for outputting a title tag:
+
+      <title><%= @page_title %></title>
+
+    === Passing local variables to sub templates
+
+    You can pass local variables to sub templates by using a hash with the variable names as keys and the objects as values:
+
+      <%= render "shared/header", { :headline => "Welcome", :person => person } %>
+
+    These can now be accessed in <tt>shared/header</tt> with:
+
+      Headline: <%= headline %>
+      First name: <%= person.first_name %>
+
+    If you need to find out whether a certain local variable has been assigned a value in a particular render call,
+    you need to use the following pattern:
+
+      <% if local_assigns.has_key? :headline %>
+        Headline: <%= headline %>
+      <% end %>
+
+    Testing using <tt>defined? headline</tt> will not work. This is an implementation restriction.
+
+    === Template caching
+
+    By default, Rails will compile each template to a method in order to render it. When you alter a template,
+    Rails will check the file's modification time and recompile it in development mode.
+
+    == Builder
+
+    Builder templates are a more programmatic alternative to ERB. They are especially useful for generating XML content. An XmlMarkup object
+    named +xml+ is automatically made available to templates with a <tt>.builder</tt> extension.
+
+    Here are some basic examples:
+
+      xml.em("emphasized")                                 # => <em>emphasized</em>
+      xml.em { xml.b("emph & bold") }                      # => <em><b>emph &amp; bold</b></em>
+      xml.a("A Link", "href" => "http://onestepback.org")  # => <a href="http://onestepback.org">A Link</a>
+      xml.target("name" => "compile", "option" => "fast")  # => <target option="fast" name="compile"\>
+                                                           # NOTE: order of attributes is not specified.
+
+    Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:
+
+      xml.div do
+        xml.h1(@person.name)
+        xml.p(@person.bio)
+      end
+
+    would produce something like:
+
+      <div>
+        <h1>David Heinemeier Hansson</h1>
+        <p>A product of Danish Design during the Winter of '79...</p>
+      </div>
+
+    A full-length RSS example actually used on Basecamp:
+
+      xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do
+        xml.channel do
+          xml.title(@feed_title)
+          xml.link(@url)
+          xml.description "Basecamp: Recent items"
+          xml.language "en-us"
+          xml.ttl "40"
+
+          @recent_items.each do |item|
+            xml.item do
+              xml.title(item_title(item))
+              xml.description(item_description(item)) if item_description(item)
+              xml.pubDate(item_pubDate(item))
+              xml.guid(@person.firm.account.url + @recent_items.url(item))
+              xml.link(@person.firm.account.url + @recent_items.url(item))
+
+              xml.tag!("dc:creator", item.author_name) if item_has_creator?(item)
+            end
+          end
+        end
+      end
+
+    More builder documentation can be found at http://builder.rubyforge.org.
+  eos
+  def show
+    unless params[:session] == "secret_hash"
+      render :text => "Not authorized", :status => 401
+      return
+    end
+    
+    unless params[:id].to_i == 5
+      render :text => "Not Found", :status => 404 and return
+    end
+    
+    render :text => "OK"
+  end
+  
+  api :desc => "Create user", :path => "/users", :method => "POST"
+  param :user, Hash, :desc => "User info" do
+    param :username, String, :desc => "Username for login", :required => true
+    param :password, String, :desc => "Password for login", :required => true
+    param :membership, ["standard","premium"], :desc => "User membership"
+  end
+  def create
+    render :text => "OK"
+  end
+
+  api :desc => "List users",
+      :path => "/users",
+      :method => "GET"
+  error :code => 401, :desc => "Unauthorized"
+  error :code => 404, :desc => "Not Found"
+  desc "List all users."
+  def index
+    render :text => "List of users"
+  end
+  
+  def doc
+    @api = Restapi['users', :show]
+  end
+end