moonrope 1.4.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8a0b6679bab153541587026c146967da03c4935
-  data.tar.gz: 7ae7f36435dba370c40d91c122041cd8cf4799f7
+  metadata.gz: 5af89a4e614e26c289fad12a69304c7a2f293562
+  data.tar.gz: e2db44de7655b8d4d3aa659fd814b1fdca6af522
 SHA512:
-  metadata.gz: b58205dfa858007e42eaf936561614184e229e56ba12033ff74d38a7ffcf5a70f4b53f0e1739ed6c1b575fa2e50e3b71b3424de7638d336be58ad5a31f5e80ce
-  data.tar.gz: eb52281364f9c559b15222cdbf5a8af671eae34ebf5238529b1fdf8b7f6c9883f55c004a3dca803d5c1f0bce98c01360fdae1dd949d7128cacdb07b448758ae0
+  metadata.gz: 90e9f623a0f62e3564fc9ba17850684f263810a04c707ff11765d12522ceef810d8524f8c93b8cc9b3a29e6a72663593552fe6050016c57c7ffe373128969d0c
+  data.tar.gz: 1d661f3d8acc4352ecc936ccbbf42d18afbefcf128db5b993e0c3edd947b84b360af8b6864e21a974b12c29c44be50e04d233c83a46afe1cce7fbd6c62704e8f

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+gemspec
+gem 'rspec'
+gem 'rspec-core'
+gem 'rspec-expectations'
+gem 'rspec-mocks'
+gem "test-unit", '~> 2.5'
+gem 'yard', '~> 0.8'
+gem "rack-test", '~> 0'

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    moonrope (2.0.0)
+      deep_merge (~> 1.0)
+      json (~> 1.7)
+      rack (>= 1.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    deep_merge (1.0.1)
+    diff-lcs (1.2.5)
+    json (1.8.3)
+    rack (1.5.2)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rake (10.3.1)
+    rspec (0.9.4)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    test-unit (2.5.5)
+    yard (0.8.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  moonrope!
+  rack-test (~> 0)
+  rake (~> 10.3)
+  rspec
+  rspec-core
+  rspec-expectations
+  rspec-mocks
+  test-unit (~> 2.5)
+  yard (~> 0.8)
+
+BUNDLED WITH
+   1.10.6

data/MIT-LICENCE

@@ -0,0 +1,20 @@
+Copyright 2014 Adam Cooke.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,24 @@
+# Moonrope - the self-documenting API
+
+Moonrope is an API server & client tool for Ruby/Rack applications. It
+provides everything you need to create an API within your application and
+have easy to use client libraries provided without any development.
+
+Not only does it provide a formal structure for your API, it will also generate
+lovely looking documentation files for develpers to work with.
+
+This repository is the server-side library which allows you to easily define
+your API actions & data structures and serve them out using Rack middleware.
+
+* [Documentation](http://rdoc.info/github/viaduct/moonrope/master/frames)
+* [Travis CI](https://travis-ci.org/viaduct/moonrope)
+
+![Screenshot](https://s.adamcooke.io/16/VJpLoJku.png)
+
+## Documentation
+
+* [Introduction](https://github.com/adamcooke/moonrope/blob/master/docs/introduction.md)
+* [Controllers & Actions](https://github.com/adamcooke/moonrope/blob/master/docs/controllers.md)
+* [Structures](https://github.com/adamcooke/moonrope/blob/master/docs/structures.md)
+* [Authentication](https://github.com/adamcooke/moonrope/blob/master/docs/authentication.md)
+* [Exceptions](https://github.com/adamcooke/moonrope/blob/master/docs/exceptions.md)

data/bin/moonrope

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+require 'moonrope'
+require 'moonrope/html_generator'
+
+if ARGV.size != 2
+  puts "usage: moonrope {path to api} {export dir}"
+  exit 1
+end
+
+api_root = ARGV[0]
+export_dir = ARGV[1]
+template_name = "basic"
+
+unless File.directory?(api_root)
+  $stderr.puts "No directory found at #{api_root}"
+  exit 1
+end
+
+if File.exists?(export_dir) && Dir[File.join(export_dir, '*')].size > 0
+  $stderr.puts "File already exists and is not empty at #{export_dir}. Delete and try again."
+  exit 1
+end
+
+base = Moonrope::Base.load(ARGV[0])
+generator = Moonrope::HtmlGenerator.new(base, File.expand_path("../../templates/#{template_name}", __FILE__))
+generator.generate(export_dir)
+puts "\e[32mMoonrope documentation generated and saved at #{export_dir}\e[0m"

data/docs/authentication.md

@@ -0,0 +1,114 @@
+# Authentication
+
+Authentication consumers to your API is a key part of developing it. Moonrope's
+authentication layer provides you with fine grained control of how your authentication
+works while still maintaining documentability.
+
+## Getting Started
+
+To begin, you need to define an `authenticator`. An authenticator's role is to
+extract an "identity" from an API request. In this example, we'll be authenticating
+our consumers using a token that will be unique to each user. The example below
+demonstrates a very simple authenticator.
+
+```ruby
+authenticator :default do
+
+  header "X-Auth-Token", "The user's unique API token.", :example => 'f29a45f0-b6da-44ae-a029-d4e1744ebaee'
+
+  error 'InvalidAPIToken', "The API token provided in X-Auth-Token was not valid.", :attributes => {:token => "The token that was looked up"}
+
+  lookup do
+    if token = request.headers['X-Auth-Token']
+      if user = User.find_by_api_token(token)
+        user
+      else
+        error 'InvalidAPIToken', :token => token
+      end
+    end
+  end
+
+  rule :default, "AccessDenied", "Must be authenticated as a user." do
+    identity.is_a?(User)
+  end
+
+  rule :anonymous, "MustBeAnonymous", "Must be anonymous." do
+    identity.nil?
+  end
+
+end
+```
+
+Let's break that down:
+
+* The first line sets the name of the authenticator. In most cases you'll only
+  ever have one which should be named `:default`. This will apply to all actions
+  in your API.
+
+* Next, we define a that the authenticator uses the `X-Auth-Token` header. We
+
+  provide a description and example for documentation purposes.
+* Next, we define that a `InvalidAPIToken` error may be raised when trying to
+  lookup the identity for the request. We include a description plus a hash of
+  attributes that should be returned with the error.
+
+* Next, we define a `lookup` block which specifies how to lookup your identity
+  object from the request. This is executed in the same scope that would be used
+  for any action in the API. This block will either return the identity object,
+  raise an error or return nothing. If it returns something, that will be used
+  as the identity object and the request will continue. If it raises an error,
+  the error will be returned to the user and the request will stop. It if returns
+  nothing, the request will continue however there will be no identity.
+
+* Next, we set a default access rule which is executed on every request to
+  verify that the identity has access to the requested action. The `default` rule
+  will apply to all actions however you can create others which can be chosen
+  for specific actions or controllers. The block for this rule must return a true
+  or false value depending on whether the identity satisfies the access condition.
+  The second argument is the error code which will be returned if this condition
+  is not satified for the request. The third argument is the description of the
+  actual condition (for documentation).
+
+* Finally, we define an anonymous rule which can be used for any actions where there
+  should not be any identity provided.
+
+## Choosing authenticators & access rules
+
+When you create actions you can choose which authenticator & access rule should
+be applied when the action is requested.  It's probably easiest to demonstrate
+this with some code:
+
+```ruby
+controller :users do
+
+  action :list do
+    # By default, this action will use the 'default' authenticator and the
+    # 'default' access rule.
+  end
+
+  action :colors do
+    # This action will use the 'default' authenticator's anonymous rule.
+    access_rule :anonymous
+  end
+
+  action :create do
+    # This action will use the 'default' access rule on the 'two_factor
+    # authenticator.
+    authenticator :two_factor
+  end
+
+  action :destroy do
+    # This action will use the 'admin' access rule on the 'two_factor'
+    # authenticator.
+    access_rule :two_factor => :admin
+  end
+
+end
+```
+
+These different actions all use different rules & authenticators. The generated
+documentation will reflect these as appropriate.
+
+It's worth noting that the `authenticator` and `access_rule` methods which are
+shown here on an action, can also be applied at the controller level and they'll
+apply to any actions that don't override them.

data/docs/controllers.md

@@ -0,0 +1,106 @@
+# Controllers & Actions
+
+Before you can create an action, you'll need to create a controller which can
+contain your action. In this example, we're going to create an action which
+will just say "Hello world!".
+
+```ruby
+controller :hello do
+  action :world do
+    description "Say hello world"
+    action do
+      "Hello world!"
+    end
+  end
+end
+```
+
+This is the most basic definition of a controller & action. It specifies the
+name of the controller (`hello`) and then adds an action to this controller.
+This action has the name `world`, a description and a block which specifies
+what you should be executed when this action is run.
+
+## Parameters
+
+It's very common to need to receive additional information when the request
+is made. Moonrope allows you to receive parameters into your action like
+normal HTTP requests.
+
+To access a paremters within your action (or helper), you can simply access
+it using `params[:name_of_parameter]` or `params.name_of_parameter`. For example,
+if you wanted to access a parameter named `page` you can use `params[:page]` or
+`params.page`. If the value sent is nil or an empty string this will return nil.
+
+### Defining supported parameters
+
+You can define which parameters are supported for actions. This is an example
+action which defines some parameters.
+
+```ruby
+action :say_hello do
+  description "Say some things to a user"
+  param :name, :required => true, :type => String
+  param :age, :required => true, :type => Integer
+  param :hair_color, :type => String, :default => 'Unknown'
+  param :phone_number, :type => String, :regex => /\A\+[\d\s]+\z/
+  action do
+    "Hello #{params.name}! You are #{params.age} and your hair is #{params.hair_color}!"
+  end
+end
+```
+
+When defining a parameter you can define a number of options to assist with
+validation & default population.
+
+* `:required => true` - this will require that this parameter is passed with
+  the request. If not an error will be raised before the action is executed.
+* `:type => String` - this sets what type of object should be submitted. In
+  most cases this should be `String`, `Integer`, `Hash` or `Array`.
+* `:default => 'Value here'` - sets the default value for the parameter if
+  none is passed.
+* `:regex => //` - sets a regex which the passed value must conform to
+
+## Raising errors
+
+If an action cannot be completed, you'll need to return an error. So that Moonrope
+can document your API, you need to define all the types of error that an action
+can return.
+
+```ruby
+action :show do
+  error "ApplicationSuspended", "The application ({app_name}) you're trying to access is suspended.", :attributes => {:app_name => "The name of the application"}
+  action do
+    if application.suspended?
+      error "ApplicationSuspended", :app_name => application.name
+    end
+  end
+end
+```
+
+In this example, you're defining an error called `ApplicationSuspended` along
+with some information about what it means plus an array of attributes which will
+be returned with it. When you're actually in the action, you're going to call that
+error by specifying the name and the attributes to provide. This will then be
+returned to the user along with the previously defined message and attributes.
+
+These will always be returned to the consumer with the `error` status.
+
+## Flags
+
+Flags contain extra information which you wish to return with your request
+without interrupting the data you are returning. Think of them like HTTP headers.
+A use case for these may be that you wish to paginate data and need to return
+pagination details along with the actual data.
+
+```ruby
+action do
+  # Get some pagianted data
+  pages = Page.paginate(:page => params.page)
+  # Set the flags
+  set_flag :current_page, pages.page
+  set_flag :items_per_page, pages.items_per_page
+  set_flag :total_pages, pages.total_pages
+  # Return all the pages as normal
+  pages
+end
+```

data/docs/exceptions.md

@@ -0,0 +1,27 @@
+# Exceptions raised during requests
+
+Moonrope will rescue any exceptions which are raised during a Rack request.
+These will be logged to the Moonrope logger and a 500 error will be returned
+to the client which made the bad request.
+
+You can also register a callback to be notified whenever an exception is raised
+in the request lifecycle. This will be useful if you want to report these
+exceptions to an external exception reporting service.
+
+This is configured by registering the callback with the Moonrope::Base instance.
+In a Rails application, this can be added as follows.
+
+```ruby
+Rails.application.config.moonrope.register_request_error_callback do |request, error|
+  tags = {
+    'component'           => 'API'
+  }
+  context = {
+    'controller'          => request.controller.try(:name).to_s,
+    'action'              => request.action.try(:name).to_s,
+    'identity'            => request.identity.is_a?(ActiveRecord::Base) ? "#{request.identity.class}##{request.identity.id}" : request.identity.to_s,
+    'params'              => request.params._as_hash
+  }
+  Raven.capture_exception(error, :tags => tags, :extra => context)
+end
+```

data/docs/introduction.md

@@ -0,0 +1,29 @@
+# The key components of a Moonrope API
+
+* **Controller** - a controller is a set of actions which can be executed by
+  users.
+
+* **Action** - an action is a method which someone can execute on your API. An
+  action may return data, update data or destroy data. Every action returns
+  some data to a user.
+
+* **Structure** - a structure allows you to convert a Ruby object (in most
+  cases this would be an Active Record model) into a hash which can be returned
+  to a user.
+
+* **Helper** - a helper is a method which you can define globally or on a
+  per controller basis. A helper can execute code & return objects which you
+  can use in your actions.
+
+These various components are defined in files which are then loaded by
+Moonrope automatically when your application starts. In a Rails application,
+by default these should be placed into a `api` directory in the root of
+your application. The actual directory structure for your Moonrope API should
+look like this:
+
+* `api/controllers` - contains all of your controllers
+* `api/structures` - contains all your structures
+* `api/helpers` - contains any helpers you have defined
+
+The name of files within these folders is not important. All files ending with
+`.rb` are loaded.

data/docs/structures.md

@@ -0,0 +1,214 @@
+# Structures
+
+A structure is a blueprint outlining out an object can be converted into a hash
+for output in your API.
+
+Say, for example, you have a User object and you wish to present this over your
+API. You would find your user and then pass this through your `user` structure
+which will return an appropriate hash based on the context the structure is
+being called from and your authenticated object.
+
+## Creating a structure
+
+Structures should be placed into your `structures` directory and best practice
+dictates they should simply be named `object_structure.rb`, for example a user structure
+would be named `user_structure.rb`.
+
+```ruby
+structure :user do
+
+  basic :id, :type => Integer, :example => 1234
+  basic :username, :type => String, :example => "adam"
+
+  full :full_name, :type => String, :example => "Adam"
+  full :last_name, :type => String, :example => "Cooke"
+  full :age, :type => Integer, :example => 27
+  full :created_at, :type => String, :example => "2014-07-01T11:32:59+01:00"
+  full :updated_at, :type => String, :example => "2014-07-01T11:32:59+01:00"
+
+end
+```
+
+This example is the most basic way of defining a structure. You see we have defined
+a number of attributes which should be included in our structure. Basic attributes are
+always included in the structure whereas full attributes are only included when requested.
+
+The basic attributes from a structure is often used on its own when referenced
+from other structures. For example, if users had many projects, the project
+structure may reference user but only request the basic information as any further
+information is not needed.
+
+The full attributes would be returned when listing a specific user or a list
+of users on their own. For example, your users/list or users/info methods would
+likely return full information rather than just the basic.
+
+Note that when full information is requested, it is always combined with the
+information from basic so there's no need to duplicate attribute definitions.
+
+### Mapping
+
+Any attributes which you add to your structure are mapped one to one with the attributes
+available on the source object. If the name doesn't match, you can use the `:name`
+option to set the actual name of the attribute on the source object.
+
+```ruby
+basic :user_id, :source_attribute => :id
+```
+
+Alternatively, you can specify a block which will be used when mapping the value to the
+correct object.
+
+```ruby
+basic :name_in_caps, :value => Proc.new { o.name.upcase }
+```
+
+### Grouping
+
+Attributes can be placed into groups which will return a hash containing all items
+within the group.
+
+```ruby
+group :financials do
+  basic :balance, :type => Integer, :example => 12345
+  full :last_invoice_raised_at, :type => String, :example => ""
+end
+```
+
+### Expansions
+
+An expansion allows you to manually define extra information which can be
+returned with your user object. For example, in some API methods you may wish
+to return extra information about the user's current financial status which
+isn't usually returned.
+
+In most cases, an expansion will be a link to another structure which you have
+defined. An expansion can be defined as shown below:
+
+```ruby
+# A single object which is associated with your user (belongs to)
+expansion :currency, :type => Hash, :structure => :currency
+# or including an array of objects (has many)
+expansion :projects, :type => Array, :structure => :project
+```
+
+The same `:structure => :name` can be used on any attribute which you define in your
+structure. Therefore, if you need to always include a structure, you can simply
+add it to a full or basic line.
+
+### Conditional attributes
+
+You can specify a condition on any attribute or expansion. This can be done by passing
+a block to the `:if` option when defining an attribute.
+
+```ruby
+condition Proc.new { identity.is_super_special_admin? }, "Only available to special admins" do
+  basic :pin
+end
+```
+
+As well as specifying inline blocks, you can also reference access rules from any
+of your authenticators.
+
+```ruby
+condition :default => :admins do
+  basic :pin
+end
+```
+
+This will use the `admins` rule on the `default` authenticator to verify whether
+or not the `pin` attribute will be displayed.
+
+If you're only using your default authenticator, you can omit the authenticator
+name in this call. For example:
+
+```ruby
+condition :admins do
+  basic :pin
+end
+```
+
+## Accessing structures from actions
+
+Now... how do you include structures from within an action I hear you ask.
+That's actually pretty simple. Throughout both actions and structures, you can
+use the `structure` method to load a structure's hash. Here are a number of
+examples which you can use to load a hash from a structure.
+
+```ruby
+# Return the basic information for a user
+structure(:user, user)
+
+# Return the full information for a user
+structure(:user, user, :full => true)
+
+# Return the full information plus all expansions
+structure(:user, user, :full => true, :expansions => true)
+
+# Return the full information plus specified expansions
+structure(:user, user, :full => true, :expansions => [:projects, :financials])
+
+# You don't need to provide the name of the structure if it can
+# be auto-determined from the name of the class.
+structure(user, :full => true)
+```
+
+Remember, these can be used in structures as well as actions. So, you may
+want to create expansions which link to other structures. For example, if you
+wanted your user hash to include a list of associated projects:
+
+```ruby
+expansion :projects do
+  o.projects.map { |p| structure(:project, p) }
+end
+```
+
+If you wish to check whether or not a structure exists before calling it from
+an action, you can use the `has_structure_for?` method as shown below.
+
+```ruby
+if has_structure_for?(:user)
+  structure(:user, user)
+else
+  error :error, "Structure not found."
+end
+```
+
+In some cases, you may wish for your consumers to decide which expansions
+should be returned. This can be achieved by passing `:paramable` when calling
+a `structure` from an action. For example:
+
+```ruby
+# Allow consumer to choose from any expansion registered on the structure.
+# (taking into account any conditions you specify) and choose whether or not
+# to include `full` attributes.
+structure(user, :paramable => true)
+
+# Allow the consumer to choose any expansions but not allow control over whether
+# full attributes should be returned. Returns all expansions by default.
+structure(user, :paramable => {:expansions => true})
+
+# Allow the consumer to choose any expansions but not allow control over whether
+# full attributes should be returned. Returns no expansions by default.
+structure(user, :paramable => {:expansions => false})
+
+# Allow consumer to choose from any expansions you list. By default, the items
+# you list will be included in the response if the user does not request any
+# specific expansions.
+structure(user, :paramable => {:expansions => [:server, :endpoint]})
+
+# Allow the consumer to control whether or not full attributes should be returned
+# in the structure or not but do not allow any control of expansions.
+structure(user, :paramable => {:full => true})
+
+# Allow the consumer to control whether or not full attributes should be returned
+# but do not return them by default.
+structure(user, :paramable => {:full => false})
+```
+
+To access these, consumers should send an `_expansions` param with their request which
+should contain an array containing the names of the expansions that should be
+included. Consumers can also send `true` or `false` in this parameter to return
+all or no expansions.
+
+To control access to `full` attributes, consumers should pass `_full` parameter
+as true or false.