haveapi 0.6.0 → 0.7.0

data/lib/haveapi/server.rb

@@ -1,10 +1,12 @@
 require 'erb'
 require 'redcarpet'
+require 'cgi'
 
 module HaveAPI
   class Server
     attr_reader :root, :routes, :module_name, :auth_chain, :versions, :default_version,
                 :extensions
+    attr_accessor :action_state
 
     include Hookable
 
@@ -16,6 +18,17 @@ module HaveAPI
             current_user: 'object returned by the authentication backend',
         }
 
+    has_hook :description_exception,
+        desc: 'Called when an exception occurs when building self-description',
+        args: {
+            context: 'HaveAPI::Context',
+            exception: 'exception instance',
+        },
+        ret: {
+            http_status: 'HTTP status code to send to client',
+            message: 'error message sent to the client',
+        }
+
     module ServerHelpers
       def authenticate!(v)
         require_auth! unless authenticated?(v)
@@ -74,6 +87,26 @@ module HaveAPI
         markdown :"../../../doc/#{file}"
       end
 
+      def base_url
+        "#{request.env['rack.url_scheme']}://#{request.env['HTTP_HOST']}"
+      end
+
+      def host
+        request.env['HTTP_HOST'].split(':').first
+      end
+
+      def urlescape(v)
+        CGI.escape(v)
+      end
+
+      def sort_hash(hash)
+        hash.sort { |a, b| a[0] <=> b[0] }
+      end
+
+      def api_version
+        @v
+      end
+
       def version
         HaveAPI::VERSION
       end
@@ -122,9 +155,12 @@ module HaveAPI
         set :views, settings.root + '/views'
         set :public_folder, settings.root + '/public'
         set :bind, '0.0.0.0'
-        set :dump_errors, true
-        set :raise_errors, true
-        set :show_exceptions, false
+
+        if settings.development?
+          set :dump_errors, true
+          set :raise_errors, true
+          set :show_exceptions, false
+        end
 
         helpers ServerHelpers
 
@@ -212,11 +248,12 @@ module HaveAPI
 
       @sinatra.get "#{@root}doc/readme" do
         content_type 'text/html'
+
         erb :main_layout do
           GitHub::Markdown.render(File.new(settings.views + '/../../../README.md').read)
         end
       end
-      
+
       @sinatra.get "#{@root}doc/json-schema" do
         content_type 'text/html'
         erb :doc_layout, layout: :main_layout do
@@ -255,7 +292,7 @@ module HaveAPI
       @auth_chain << HaveAPI.default_authenticate if @auth_chain.empty?
       @auth_chain.setup(@versions)
 
-      @extensions.each { |e| e.enabled }
+      @extensions.each { |e| e.enabled(self) }
 
       # Mount default version first
       mount_version(@root, @default_version)
@@ -279,6 +316,7 @@ module HaveAPI
             user: current_user,
             params: params
         ))
+
         content_type 'text/html'
         erb :doc_layout, layout: :main_layout do
           @content = erb :version_page
@@ -298,10 +336,20 @@ module HaveAPI
         )))
       end
 
+      # Register blocking resource
       HaveAPI.get_version_resources(@module_name, v).each do |resource|
         mount_resource(prefix, v, resource, @routes[v][:resources])
       end
 
+      if action_state
+        mount_resource(
+            prefix,
+            v,
+            HaveAPI::Resources::ActionState,
+            @routes[v][:resources]
+        )
+      end
+
       validate_resources(@routes[v][:resources])
     end
 
@@ -350,7 +398,11 @@ module HaveAPI
 
     def mount_action(v, route)
       @sinatra.method(route.http_method).call(route.url) do
-        authenticate!(v) if route.action.auth
+        if route.action.auth
+          authenticate!(v)
+        else
+          authenticated?(v)
+        end
 
         request.body.rewind
 
@@ -370,6 +422,7 @@ module HaveAPI
         action = route.action.new(request, v, params, body, Context.new(
             settings.api_server,
             version: v,
+            request: self,
             action: route.action,
             url: route.url,
             params: params,
@@ -381,15 +434,19 @@ module HaveAPI
           report_error(403, {}, 'Access denied. Insufficient permissions.')
         end
 
-        status, reply, errors = action.safe_exec
+        status, reply, errors, http_status = action.safe_exec
+        @halted = true
 
-        @formatter.format(
-            status,
-            status  ? reply : nil,
-            !status ? reply : nil,
-            errors,
-            version: false
-        )
+        [
+            http_status || 200,
+            @formatter.format(
+                status,
+                status  ? reply : nil,
+                !status ? reply : nil,
+                errors,
+                version: false
+            ),
+        ]
       end
 
       @sinatra.options route.url do |*args|
@@ -398,26 +455,38 @@ module HaveAPI
 
         pass if params[:method] && params[:method] != route_method
 
-        authenticate!(v) if route.action.auth
+        if route.action.auth
+          authenticate!(v)
+        else
+          authenticated?(v)
+        end
+
+        ctx = Context.new(
+            settings.api_server,
+            version: v,
+            request: self,
+            action: route.action,
+            url: route.url,
+            args: args,
+            params: params,
+            user: current_user,
+            endpoint: true
+        )
 
         begin
-          desc = route.action.describe(Context.new(
-              settings.api_server,
-              version: v,
-              action: route.action,
-              url: route.url,
-              args: args,
-              params: params,
-              user: current_user,
-              endpoint: true
-          ))
+          desc = route.action.describe(ctx)
 
           unless desc
             report_error(403, {}, 'Access denied. Insufficient permissions.')
           end
 
-        rescue ActiveRecord::RecordNotFound
-          report_error(404, {}, 'Object not found')
+        rescue => e
+          tmp = settings.api_server.call_hooks_for(:description_exception, args: [ctx, e])
+          report_error(
+              tmp[:http_status] || 500,
+              {},
+              tmp[:message] || 'Server error occured'
+          )
         end
 
         @formatter.format(true, desc)

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
-  PROTOCOL_VERSION = '1.0'
-  VERSION = '0.6.0'
+  PROTOCOL_VERSION = '1.1'
+  VERSION = '0.7.0'
 end

data/lib/haveapi/views/main_layout.erb

@@ -7,6 +7,10 @@
   <link rel="stylesheet" href="/css/bootstrap.min.css">
   <script src="/js/jquery-1.11.1.min.js"></script>
   <script src="/js/bootstrap.min.js"></script>
+  <script src="/js/nojs-tabs.js"></script>
+  <link rel="stylesheet" href="/css/highlight.css">
+  <script src="/js/highlight.pack.js"></script>
+  <script src="/js/main.js"></script>
 
   <style>
     /*.resource { margin-left: 10px; }*/
@@ -47,6 +51,16 @@
       padding: 5px 0px;
       margin-left: 18px;
     }
+    .tab-hidden {
+      display: none;
+    }
+    pre {
+      overflow: auto;
+    }
+    pre code {
+      word-wrap: normal;
+      white-space: pre;
+    }
   </style>
 </head>
 <body data-spy="scroll" data-target=".table-of-contents">

data/lib/haveapi/views/version_page.erb

@@ -21,14 +21,68 @@ def format_validators(validators)
 end
 %>
 
-<% def render_resource_body(resource, info, prefix='root', name=nil) %>
+<% def render_auth_body(name, info) %>
+  <h2 id="auth-<%= name %>"><%= name.to_s.humanize %></h2>
+  <hr>
+
+  <p><%= info[:description] %></p>
+
+  <% if name == :token %>
+    <dl>
+      <dt>HTTP header:</dt>
+      <dd><%= info[:http_header] %></dd>
+      <dt>Query parameter:</dt>
+      <dd><%= info[:query_parameter] %></dd>
+    </dl>
+  <% end %>
+
+  <% if info[:resources] %>
+    <h2>Resources</h2>
+    <% sort_hash(info[:resources]).each do |resource, desc| %>
+      <% render_resource_body(resource.to_s, desc, 'auth') %>
+    <% end %>
+  <% end %>
+
+  <% baseid = "auth-#{name}" %>
+  <div id="<%= baseid %>-tabbar"></div>
+
+  <div id="<%= baseid %>-examples">
+    <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
+      <div id="<%= "#{baseid}-#{i}" %>">
+        <% render_client_auth(client, name, info) %>
+      </div>
+    <% end %>
+  </div>
+
+  <script type="text/javascript">
+  nojsTabs({
+    tabs: document.getElementById('<%= "#{baseid}-examples" %>'),
+    titleSelector: 'h4',
+    tabBar: document.getElementById('<%= "#{baseid}-tabbar" %>'),
+    hiddenClass: 'tab-hidden',
+    activeClass: 'active',
+    createElement: function (el) {
+      if (el.tagName == 'UL')
+        el.classList.add('nav', 'nav-tabs');
+
+      else if (el.tagName == 'LI')
+        el.setAttribute('role', 'presentation');
+    }
+  });
+  </script>
+<% end %>
+
+<% def render_resource_body(resource, info, path = [], prefix='root', name=nil) %>
   <% name ||= resource.humanize %>
+  <% resource_path = path.clone << resource %>
+  <% resource_info = info %>
   <h2 class="resource" id="<%= "#{prefix}-#{resource}" %>"><%= resource.humanize %></h2>
+  <hr>
   <div class="resource-body">
     <p><%= info[:description] %></p>
 
     <div class="actions">
-      <% info[:actions].each do |action, info| %>
+      <% sort_hash(info[:actions]).each do |action, info| %>
         <h3 id="<%= "#{prefix}-#{resource}-#{action}" %>"><%= name %> # <%= action.capitalize %></h3>
         <div class="action">
           <dl>
@@ -40,6 +94,8 @@ end
             <dd><%= info[:auth] ? 'yes' : 'no' %></dd>
             <dt>Aliases:</dt>
             <dd><%= info[:aliases].join(', ') %></dd>
+            <dt>Blocking:</dt>
+            <dd><%= info[:blocking] ? 'yes' : 'no' %></dd>
           </dl>
 
           <h4>Input parameters</h4>
@@ -54,7 +110,7 @@ end
                 <dd><%= info[:input][:namespace] %></dd>
               </dl>
 
-              <table class="table table-striped table-hover">
+              <table class="table table-striped table-hover table-bordered">
                 <tr>
                   <th>Label</th>
                   <th>Name</th>
@@ -91,7 +147,7 @@ end
                 <dd><%= info[:output][:namespace] %></dd>
               </dl>
 
-              <table class="table table-striped table-hover">
+              <table class="table table-striped table-hover table-bordered">
                 <tr>
                   <th>Label</th>
                   <th>Name</th>
@@ -117,15 +173,47 @@ end
 
           <% unless info[:examples].empty? %>
             <h4>Examples</h4>
-            <% info[:examples].each do |example| %>
-                <h5><%= example[:label] %></h5>
+            <% info[:examples].each_with_index do |example, i| %>
+                <h5><%= example[:title].empty? ? "Example ##{i}" : example[:title] %></h5>
                 <p><%= example[:comment] %></p>
 
-                <h6>Request</h6>
-                <pre><code><%= JSON.pretty_generate(example[:request]) %></code></pre>
+                <% baseid = "example-#{resource_path.join('.')}-#{action}-#{i}" %>
+                <%# placeholder for tabs %>
+                <div id="<%= "#{baseid}-tabbar" %>"></div>
+
+                <div id="<%= "#{baseid}-examples" %>">
+                  <% HaveAPI::ClientExample.clients.each_with_index do |client, j| %>
+                    <div id="<%= "#{baseid}-#{j}" %>">
+                      <%
+                        render_client_example(
+                          client,
+                          resource_path,
+                          resource_info,
+                          action,
+                          info,
+                          example
+                        )
+                      %>
+                    </div>
+                  <% end %>
+                </div>
+
+                <script type="text/javascript">
+                nojsTabs({
+                  tabs: document.getElementById('<%= "#{baseid}-examples" %>'),
+                  titleSelector: 'h6',
+                  tabBar: document.getElementById('<%= "#{baseid}-tabbar" %>'),
+                  hiddenClass: 'tab-hidden',
+                  activeClass: 'active',
+                  createElement: function (el) {
+                    if (el.tagName == 'UL')
+                      el.classList.add('nav', 'nav-tabs');
 
-                <h6>Response</h6>
-                <pre><code><%= JSON.pretty_generate(example[:response]) %></code></pre>
+                    else if (el.tagName == 'LI')
+                      el.setAttribute('role', 'presentation');
+                  }
+                });
+                </script>
             <% end %>
           <% end %>
 
@@ -134,24 +222,110 @@ end
     </div>
 
     <% unless info[:resources].empty? %>
-      <% info[:resources].each do |r, i| %>
-        <% render_resource_body(r, i, "#{prefix}-#{resource}", "#{name}.#{r.humanize}") %>
+      <% sort_hash(info[:resources]).each do |r, i| %>
+        <% render_resource_body(r, i, resource_path, "#{prefix}-#{resource}", "#{name}.#{r.humanize}") %>
       <% end %>
     <% end %>
 
   </div> <!-- resource -->
 <% end %>
 
+<% def render_client_init(client) %>
+  <h4><%= client.label %></h4>
+  <pre><code class="<%= client.code %>"><%= client.init(host, base_url, api_version) %></code></pre>
+<% end %>
+
+<% def render_client_auth(client, method, desc) %>
+  <h4><%= client.label %></h4>
+  <pre><code class="<%= client.code %>"><%= client.auth(host, base_url, api_version, method, desc) %></code></pre>
+<% end %>
+
+<% def render_client_example(client, r_name, resource, a_name, action, example) %>
+  <h6><%= client.label %></h6>
+  <% sample = client.new(host, base_url, api_version, r_name, resource, a_name, action) %>
+  <% if sample.respond_to?(:example) %>
+    <pre><code class="<%= client.code %>"><%= sample.example(example) %></code></pre>
+
+  <% else %>
+    <h6>Request</h6>
+    <pre><code class="<%= client.code %>"><%= sample.request(example) %></code></pre>
+    <h6>Response</h6>
+    <pre><code class="<%= client.code %>"><%= sample.response(example) %></code></pre>
+  <% end %>
+<% end %>
+
+
 <h1 id="api">API v<%= @v %></h1>
+
+<ol class="breadcrumb">
+  <li><a href="<%= root %>"><%= host %></a></li>
+  <li class="active">v<%= @v %></li>
+</ol>
+
 <p>
   This page contains a list of resources available in API v<%= @v %>, their actions,
   description, parameters and example usage.
 </p>
 
+<p>
+  This API is based on the <a href="https://github.com/vpsfreecz/haveapi">HaveAPI</a> framework.
+  You can access it using existing clients:
+</p>
+
+<ul>
+  <li><a href="https://github.com/vpsfreecz/haveapi-client" target="_blank">Ruby library and CLI</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi-client-js" target="_blank">JavaScript</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi-client-php" target="_blank">PHP</a></li>
+  <li>
+    <a href="https://github.com/vpsfreecz/haveapi-webui" target="_blank">Generic web interface</a>
+    (<a href="https://webui.haveapi.org/v<%= version %>/#<%= escape(base_url) %>" target="_blank">connect to this API</a>)
+  </li>
+  <li><a href="https://github.com/vpsfreecz/haveapi-fs" target="_blank">FUSE-based file system</a></li>
+</ul>
+
+<p>
+  The code examples found on this page are for HaveAPI v<%= version %>, so be sure
+  to use clients of the same version.
+</p>
+
+<h2>Initialization</h2>
+
+<div id="init-tabbar"></div>
+
+<div id="init-examples">
+  <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
+    <div id="<%= "init-#{i}" %>">
+      <% render_client_init(client) %>
+    </div>
+  <% end %>
+</div>
+
+<script type="text/javascript">
+nojsTabs({
+  tabs: document.getElementById('init-examples'),
+  titleSelector: 'h4',
+  tabBar: document.getElementById('init-tabbar'),
+  hiddenClass: 'tab-hidden',
+  activeClass: 'active',
+  createElement: function (el) {
+    if (el.tagName == 'UL')
+      el.classList.add('nav', 'nav-tabs');
+
+    else if (el.tagName == 'LI')
+      el.setAttribute('role', 'presentation');
+  }
+});
+</script>
+
+<h1 id="auth">Authentication methods</h1>
+<% @help[:authentication].each do |name, info| %>
+    <% render_auth_body(name, info) %>
+<% end %>
+
 <h1 id="resources">Resources</h1>
 <p>Follows a list of all resources in this API and their actions.</p>
 
-<% @help[:resources].each do |resource, info| %>
+<% sort_hash(@help[:resources]).each do |resource, info| %>
     <% render_resource_body(resource, info) %>
 <% end %>
 </div>