daylight 0.9.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a160432a89b2031c5897592fcf570c6de41cef69
+  data.tar.gz: 52b800d5206e184a13cb0eaf1dc721b4af820897
+SHA512:
+  metadata.gz: 9b5aa0bfa3e0524fc7d2b86052fb7137bbcdd75c86d21d34346b89cf81240c4311f2b5554b2d56144f2f0565a0668e9ef8c7939e1f815e50b17ee6a7a67deae1
+  data.tar.gz: e97de04202276572bd099e6b9244b840087110effa934d73949b11150714e3f21ccff519ed119f70817cb60bb2b0691612c1daf97ecfd01a80d0470c1cc8bd72

data/README.md

@@ -0,0 +1,113 @@
+# Daylight
+
+Daylight extends Rails and ActiveResource to allow your client API to perform
+akin to ActiveRecord
+
+Features include those like ActiveRecord such as scopes, `find_by` lookups,
+calling associations on  server-side models, using through associations, and
+the ability to chain queries.  Eases requesting complex queries on your Rails
+models using `remoted` methods.
+
+Typical ActiveResource functionality:
+
+  ````ruby
+  API::Post.all                                      # index request
+  API::Post.published                                # client-based association
+  API::Post.find(1)                                  # show request
+  ````
+
+Daylight adds to ActiveResource with chained queries:
+
+  ````ruby
+  API::Post.where(author_id: 1)                      # simple query
+  API::Post.where(author_id: 1).first                # chained query
+  API::Post.where(author_id: 1).published            # chained query with scope
+  API::Post.where(author_id: 1).published.recent     # chained query with multiple scopes
+  API::Post.where(author_id: 1).limit(10).offset(20) # chained query with limit and offset
+  API::Post.where(author_id: 1).order(:date)         # chained query with ordering
+
+  API::Post.find_by(slug: '100-best-albums-2014')    # find_by lookup gets first match
+  ````
+
+Daylight can also chain queries on an ActiveResource's association.  All of the
+chain queries above can be used to refine searches on associations:
+
+  ````ruby
+  API::Post.first.comments                           # lookup and association
+  API::Post.first.comments.where(user_id: 2)         # query on lookup's association
+  API::Post.first.comments.where(user_id: 2).first   # chained query on
+  API::Post.first.comments.where(user_id: 2).edited  # chained query with scope
+                                                     # etc.
+  ````
+
+Daylight allows you to return collections from complex queries on your model:
+
+  ````ruby
+  API::Post.first.top_comments
+  ````
+
+Daylight packages API query details in one request when it can to lower
+the network overhead.
+
+Daylight allows you to query for a record before initializing or creating it
+using ActiveRecord's familiar `first_or_create` and `first_or_initialize`
+methods.
+
+  ````ruby
+  post = API::Post.new(slug: '100-best-albums-2014')
+  post.author = API::User.find_or_create(username: 'reidmix')
+  post.save
+  ````
+
+The last query to the database uses Rails' `accepts_nested_attributes_for`
+and the `User` could have easily been setup with `find_or_initialize` to
+reduce the number of server-side queries.
+
+More information can be found in the [Daylight Users Guide](doc/usage.md).
+
+## Getting Started
+
+1. Install Daylight both on your server and your client.
+
+        gem install daylight
+
+2. On your server, add a rails initializer:
+
+    ````ruby
+    require 'daylight/server'
+    ````
+
+3. On your client, setup your API:
+
+    ````ruby
+    Daylight::API.setup!(endpoint: 'http://localhost/')
+    ````
+
+4. Use your client models to query your API!
+
+## Development
+
+Ah, but we have to develop our API and client models:
+
+1. Develop your Rails models, controllers, and routes like you do today.  Add
+   a serializer for each model in the API.  Daylight provides additions to
+   simplify adding features to your controllers and routes.
+
+2. Develop your client models using Daylight's extensions to ActiveResource.
+   Daylight provides Mocks to aid in full stack testing of your client models.
+
+3. Consider versioning your client models and distribute them using a gem.
+   Daylight supports versioned APIs and has facilities available for your
+   development.
+
+4. More information can be found on:
+    * [Installation Steps](doc/install.md)
+    * [Daylight Users Guide](doc/usage.md)
+    * [API Developer Guide](doc/develop.md)
+    * [Testing Your API](doc/testing.md)
+    * [How to Contribute](doc/contribute.md)
+
+## License
+
+Daylight is released under the [Apache License](http://www.apache.org/licenses/LICENSE-2.0).
+First released on June 30th, 2014.

data/app/controllers/daylight_documentation/documentation_controller.rb

@@ -0,0 +1,27 @@
+##
+# Controller that handles rendering the API Documentation
+class DaylightDocumentation::DocumentationController < ActionController::Base
+  layout 'documentation'
+
+  caches_page :index, :model
+
+  ##
+  # Index of all the models/endpoints
+  def index
+    @models = models
+  end
+
+  ##
+  # Model description
+  def model
+    model_name = params[:model]
+    @model = models.find { |model| model.name.underscore == model_name }
+  end
+
+  private
+
+  def models
+    Rails.application.eager_load!
+    ActiveRecord::Base.descendants
+  end
+end

data/app/helpers/daylight_documentation/documentation_helper.rb

@@ -0,0 +1,57 @@
+##
+# Helper methods for rendering the endpoint/model documentation.
+module DaylightDocumentation::DocumentationHelper
+
+  ACTION_DEFINITIONS = {
+    'index'      => "Retrieves a list of %{names}",
+    'create'     => "Creates a new %{name}",
+    'show'       => "Retrieves a %{name} by an ID",
+    'update'     => "Updates a %{name}",
+    'associated' => "Returns %{name}\'s %{associated}",
+    'remoted'    => "Calls %{name}\'s remote method %{remoted}"
+  }
+
+  ##
+  # Yield all of the route information for the given model.
+  #
+  # Yields route verb (GET, POST, etc), path specification, route defaults
+  def model_verbs_and_routes(model)
+    routes = Daylight::Documentation.routes.routes.select {|route| route.path.spec.to_s.include? "/#{model.name.underscore.pluralize}" }
+
+    routes.each do |route|
+      yield route_verb(route), route.path.spec, route.defaults
+    end
+  end
+
+  ##
+  # A list of all the possible filters for the given model.
+  def model_filters(model)
+    model.attribute_names + model.reflection_names
+  end
+
+  ##
+  # A description of a route given the route defaults and model class.
+  def action_definition(defaults, model)
+    ACTION_DEFINITIONS[defaults[:action]] % {
+      name:       model.name.titleize.downcase,
+      names:      model.name.titleize.pluralize.downcase,
+      associated: defaults[:associated].to_s.pluralize.tr('_', ' '),
+      remoted:    defaults[:remoted]
+    }
+  end
+
+  def client_namespace
+    Daylight::API.namespace
+  end
+
+  def api_version
+    Daylight::API.version.downcase
+  end
+
+  private
+
+    def route_verb(route)
+      %w[GET POST PUT PATCH DELETE].find {|verb| verb =~ route.verb}
+    end
+
+end

data/app/views/daylight_documentation/documentation/_header.haml

@@ -0,0 +1,4 @@
+%nav.navbar.navbar-default{role: 'navigation'}
+  .container-fluid
+    .navbar-header
+      =link_to Daylight::API.namespace, :index, class: 'navbar-brand'

data/app/views/daylight_documentation/documentation/index.haml

@@ -0,0 +1,12 @@
+- content_for :title, "#{Daylight::API.namespace} :: API"
+
+.container
+
+  .page-header
+    %h1 Models
+
+  .row
+    - @models.sort_by(&:name).each_slice(1+@models.count/3) do |group|
+      .list-group.col-md-3
+        - group.each do |model|
+          =link_to model.name, model_path(model.name.underscore), class: 'list-group-item'

data/app/views/daylight_documentation/documentation/model.haml

@@ -0,0 +1,114 @@
+- content_for :title, "#{client_namespace} :: #{@model.name} API"
+
+.container
+
+  .row
+
+    .col-md-9
+      .page-header
+        %h1= @model.name
+
+      #api.panel.panel-default
+        .panel-heading
+          %h3 API
+        %table.table.table-condensed
+          - model_verbs_and_routes(@model) do |verb, path, defaults|
+            %tr
+              %td= defaults[:action].capitalize
+              %td= verb
+              %td= path
+              %td= action_definition(defaults, @model)
+
+      #filters.panel.panel-default
+        .panel-heading
+          %h3.panel-title Filters
+        .panel-body
+          %ul.list-inline
+          - model_filters(@model).each do |filter|
+            %li.btn.btn-default= filter
+
+          - attribute = @model.attribute_names.second
+          %h4 API Examples
+          %pre
+            == /#{api_version}/#{@model.name.underscore.pluralize}.json?filters[#{attribute}]=foo
+
+          %h4 Client Examples
+          %pre
+            == #{client_namespace}::#{@model.name}.where(#{attribute}: 'foo')
+
+      - scopes = @model.registered_scopes
+      - if scopes.present?
+        #scopes.panel.panel-default
+          .panel-heading
+            %h3.panel-title Scopes
+
+          .panel-body
+            %ul.list-group
+              - scopes.each do |scope|
+                %li.list-group-item= "#{@model.name}.#{scope}"
+
+            %h4 API Examples
+            %pre
+              ==/#{api_version}/#{@model.name.underscore.pluralize}.json?scopes[]=#{scopes.first}
+              - if scopes.count > 1
+                %br<>
+                == /#{api_version}/#{@model.name.underscore.pluralize}.json?scopes[]=#{scopes.first}&scopes[]=#{scopes.last}
+
+            %h4 Client Examples
+            %pre
+              == #{client_namespace}::#{@model.name}.#{scopes.first}
+              - if scopes.count > 1
+                %br<>
+                == #{client_namespace}::#{@model.name}.#{scopes.first}.#{scopes.last}
+
+      #associations.panel.panel-default
+        .panel-heading
+          %h3.panel-title Associations
+        .panel-body
+          %ul.list-group
+            - @model.reflections.each_pair do |key, reflection|
+              %li.list-group-item
+                %a{title: reflection.klass.name, href: "#{reflection.klass.name.downcase}.html"}= reflection.name
+
+          - reflections = @model.reflection_names.grep /s$/
+          - if reflections.present?
+            %h4 API Examples
+            %pre
+              ==/#{api_version}/#{@model.name.underscore.pluralize}/1/#{reflections.first}.json
+
+            %h4 Client Examples
+            %pre
+              ==#{@model.name.underscore}.#{reflections.first}
+
+      #client-examples.panel.panel-default
+        .panel-heading
+          %h3.panel-title Other Client Examples
+        .panel-body
+          %pre
+            #{client_namespace}::#{@model.name}.first
+            %br<>
+            #{client_namespace}::#{@model.name}.find(1)
+            - reflection = @model.reflections.values.find {|ref| ref.macro == :has_many }
+            - if reflection
+              %br<>
+              #{client_namespace}::#{@model.name}.find(1).#{reflection.name}
+              %br<>
+              #{client_namespace}::#{@model.name}.find(1).#{reflection.name} &lt;&lt; #{client_namespace}::#{reflection.klass.name}.find(2)
+              - filter = reflection.klass.attribute_names.last
+              %br<>
+              #{client_namespace}::#{@model.name}.find(1).#{reflection.name}.where(#{filter}: filter_value)
+              %br<>
+              #{client_namespace}::#{@model.name}.find(1).#{reflection.name}.where(#{filter}: filter_value).first_or_create
+
+    #navigation.col-md-3
+      %ul.nav.nav-pills.nav-stacked.affix
+        %li.active
+          %a{href:'#api'} API
+        %li
+          %a{href:'#filters'} Filters
+        %li
+          %a{href:'#scopes'} Scopes
+        %li
+          %a{href:'#associations'} Associations
+        %li
+          %a{href:'#client-examples'} Client Examples

data/app/views/layouts/documentation.haml

@@ -0,0 +1,22 @@
+!!! 5
+%html
+  %head
+    %meta{charset: "utf-8"}
+    %meta{name: "viewport", content: "width=device-width, initial-scale=1"}
+
+    %link{rel: "stylesheet", href: "https://netdna.bootstrapcdn.com/bootstrap/3.1.0/css/bootstrap.min.css"}
+    %script{src: "https://code.jquery.com/jquery-1.10.1.min.js"}
+    %script{src: "https://netdna.bootstrapcdn.com/bootstrap/3.1.0/js/bootstrap.min.js"}
+
+    %title= yield :title
+
+    :css
+      .spacer20 { height: 20px; width: 100%; font-size: 0; margin: 0; padding: 0; border: 0; display: block; }
+      .spacer50 { height: 50px; width: 100%; font-size: 0; margin: 0; padding: 0; border: 0; display: block; }
+      .btn-lg   { font-size: 40px; }
+
+  %body{:'data-spy' => "scroll", :'data-target' => "#navigation"}
+
+    = render 'header'
+
+    = yield

data/config/routes.rb

@@ -0,0 +1,8 @@
+Daylight::Documentation.routes.draw do
+
+  with_options controller: 'documentation' do |c|
+    c.get '/',      action: :index, as: 'index'
+    c.get ':model', action: :model, as: 'model'
+  end
+
+end

data/doc/actions.md

@@ -0,0 +1,70 @@
+# Controller Actions
+
+When your `APIController` handles all requests, like so:
+
+  ````ruby
+
+    class PostController < APIController
+      handles :all
+    end
+
+  ````
+
+Essentially, these are the actions that are run on its behalf:
+
+  ````ruby
+
+    class PostController < APIController
+
+      # GET /posts.json
+      #
+      def index
+        render json: Post.refine_by(params)
+      end
+
+
+      # POST /posts.json
+      #
+      def create
+        @post = Post.new(params[:post])
+        @post.save!
+
+        render json: @post, status: :created, location: @post
+      end
+
+      # GET /posts/1.json
+      #
+      def show
+        render json: Post.find(params[:id])
+      end
+
+      # PATCH/PUT /posts/1.json
+      #
+      def update
+        Post.find(params[:id]).update!(params[:post])
+
+        head :no_content
+      end
+
+      # DELETE /posts/1.json
+      #
+      def destroy
+        Post.find(params[:id]).destroy
+
+        head :no_content
+      end
+
+      # GET /posts/1/comments.json
+      #
+      def associated
+        render json: Post.associated(params), root: associated_params
+      end
+
+      # GET /posts/1/all_authorized_users.json
+      #
+      def remoted
+        render json: Post.remoted(params), root: remoted_params
+      end
+    end
+
+  ````

data/doc/benchmarks.md

@@ -0,0 +1,17 @@
+# Benchmarks
+
+Placeholder to show benchmarks of `Daylight` requests and responses.
+
+
+## LOC Statistics
+
+As an exercise we look at the lines of code at the time of writing this
+documentation.  Excluding comments and empty lines, `Daylight` is really
+tiny:
+
+| Where      |  LOC |
+| ---------- | ---: |
+| Client     |  490 |
+| Server     |  507 |
+| Mock       |  174 |
+| **Total**  | 1171 |

data/doc/contribute.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Daylight: the intial release.  We encourage you to contribute, explore
+our new framework, to seek out strange new bugs and build new possiblities,
+to boldly go where we have not gone before.
+
+## History
+
+Daylight was built as an API for a web application on the AT&T Cloud team
+using the domain model needed for several tasks in the organization.  We
+wanted to be able to lift sections of our codebase out of the monolithic
+codebase with little-to-no code changes between `ActiveRecord` and
+`ActiveResource`.
+
+The functionality was built for the organization's usecases and while
+documenting, we've noticed "holes" or possiblities within the codebase.
+
+Daylight is the extracted files that sat between our API models and the
+Rails components.  We've also extracted some of our tools such as the
+mocking framework we built and Documentation Rails engine with hopes
+that they might serve useful to API developers.
+
+Daylight is named as such for our intent the framework would be able to
+"_see the light of day_".
+
+## Reporting an Issue
+
+We are using Github's [Issues](https://github.com/att-cloud/daylight/issues)
+to track all future work and bugs.  Please investigate if there is a bug
+already submitted for your the issue you've found and if not, submit a
+[new issue](https://github.com/att-cloud/daylight/issues/new).
+
+Include a title and a clear statement of a problem.  If you can, add the
+steps to reproduce, a backtrace, the Daylight gem version as well as the
+Rails & ActiveModelSerializer version numbers.  Please include example
+code when possible.
+
+## Contributing to the Codebase
+
+Daylight is a self-contained, running rspec tests against a _dummy_ Rails
+application backed by a sqlite database.  Once you have your
+[build Environment](environment.md) up and running, you will be able to
+run the tests.
+
+Clone (or fork) the Daylight repository:
+
+    $ git clone git://github.com/att-cloud/daylight.git
+
+Switch to your own branch:
+
+    $ cd daylight
+    $ git checkout -b my_branch
+
+Build your code and tests.  Ensure they all run, see if you a missing any
+tests:
+
+    $ cd daylight
+    $ rake spec
+    $ rake rcov
+
+Commit your changes:
+
+    $ git commit -a
+
+Issue a [pull request](#https://help.github.com/articles/using-pull-requests)
+using your branch with your code changes.
+
+## Understanding
+
+To better understand how a framework extends or alters the underlying Rails
+technology and help navigate the code for contributing, here are details and
+guidelines on how Daylight was built.
+
+Please rely on the following for reference or feel free to ask or suggest
+improvements:
+
+* [Guiding Principles](principles.md)
+* [Build Environment](environment.md)
+* [Framework Overview](framework.md)
+* [Daylight Benchmarks](benchmarks.md)