jsonapionify 0.11.9 → 0.11.10

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Njg2MWVkODk4NWRkZjBlMTRjYzVhY2NjNzgwYzM3ZmFmNDU4NTVlZQ==
+    Nzg2ZGJhNjcxNmEzOTJmYWI4MjlkODQ5YjhhZWZkYWY5MjlkMTUyNQ==
   data.tar.gz: !binary |-
-    NWFlZjllMzM3NmRhNDIzYjRmOTkxYzA0Yzg4ZDY3YmIxYzU0ZjE2OA==
+    YzE3OWY1MTA0ODhiZGZiNmZkMjcwYTZkMGRiZjFmY2ZlNjE0NmVhNQ==
 SHA512:
   metadata.gz: !binary |-
-    Zjg4Y2YzMGQ3YTMzYzZhNjE5YTM1NTRjZDMyODA3ZmVmNzA5ZGRkOTk3NWQ1
-    YzQ2MGRjM2JjODMzMWUzZjRjZmJmZjk5MGJmMWMwNzJlZjkwYWU1OGQ2MzVj
-    ZjA4NWU0NzU4MjJjZGIwNTFhMWU0MmJjZDUwNmRlMWIxYmZmODI=
+    ODE4MDFiZDFmOTlmNzBiOGU3ZDVlOTQ0YTE3NmMzYmU0Y2ZiM2EwNGIxMzcz
+    OTNlYWZlNDEzNmI5ZjBkNTdiNTBmNzNiYWIwZGUxNGMzZmJmNzE2NzQ1ZDc4
+    MzkyYTE3MWM4MDU5ODdkYmMwYjQ2ZWEyNTY5Yzc5ODU1MjgxZGY=
   data.tar.gz: !binary |-
-    MDA1ZDA5ZGFkMjQyMWZhM2NjYzc2OTU5MTZhNDNjMTliZjU4Y2QwYTczYzU3
-    ODhmNDI2OThkOTY0NmNiOTJhM2RjNmNhYTU1OTI0YWJiOTY2OTQ5YmZiYWQ1
-    ZDNlNjI3YmVkMjhiZDI4ODk1ZTI1ZjYxMGFlZDQ2OTM1Zjk0Y2M=
+    ZmU0NjY3YzU0ZDUyZjA0ZDY1NWM2N2NhZjQyZWY4NmJlODQ3OTI1ZjBiYTJl
+    NjAwMjM3OTgyZDU0OGQwMDM4YzZjNjYyODEzMWU2MDA5N2YwMjYxZjMwNjUx
+    MDk5YWViNTIxZTBjZTE0NDdkZmM4NWMxMTEzYTJkNzY3MjQ4NjM=

data/README.md

@@ -29,91 +29,200 @@ And then execute:
 
 ## Usage
 
-### Context: Read First
+### APIs
 
-Before we get started with defining an API, you should understand a pattern used heavily throughout JSONAPIonify. This pattern is called a context. A context is a definition of data that is memoized and passed around a request. You may see context used as follows:
+Api Definitions are the basis of JSONApi's DSL. They encompass resources that are available and can be run as standalone rack apps or be mounted within a rails app.
+
+```
+class MyCompanyApi < JSONAPIonify::Base
+
+  # Write a description for your API.
+  description <<~markdown
+  A description of your API, that will be available at the top of the documentation.
+  markdown
+
+  # Add some rack middleware
+  use Rack::SSL::Enforcer
+
+  # Handle Authorization
+
+end
+```
+
+### Resources
+
+Resources are what the API serves. They usually link to models. Resources are defined by calling `.define_resource` on the class of a defined api.
 
 ```ruby
-before :create do |context|
-  puts context.request.request_method
+MyCompanyApi.define_resource :users do
+  # ... The resource definition
 end
 ```
 
-Contexts can also call other contexts within their definitions:
+#### Scope
+Each api uses a scope to determine how to look up objects the serve the request. By default the resource will look for a class that is similar to it's scope.
 
 ```ruby
-context :request_method do |context|
-  context.request.request_method
+MyCompanyApi.define_resource :users do
+  scope { Person }
 end
 ```
 
-JSONApionify already ships with a set of predefined contexts.
+#### ID Attribute
+JSONAPI needs an attribute to represent the object's id. This defaults to the `id` method, but can be overridden.
 
-### Create an API
+```ruby
+MyCompanyApi.define_resource :users do
+  id :key
+end
+```
 
-Api Definitions are the basis of JSONApi's DSL. They encompass resources that are available and can be run as standalone rack apps or be mounted within a rails app.
+#### Instance Lookup
+In order to locate an instance in the defined scope, the resource needs a instructions to do so. If the scope is a descendant of `ActiveRecord::Base`, it will automatically use `scope.find(id)` for the lookup.
 
+```ruby
+MyCompanyApi.define_resource :users do
+  instance { |scope, id| scope.find_by key: id }
+end
 ```
-class MyCompanyApi < JSONAPIonify::Base
 
-  # Write a description for your API.
-  description <<~markdown
-  A description of your API, that will be available at the top of the documentation.
-  markdown
-  
-  # Add some rack middleware
-  use Rack::SSL::Enforcer
-  
-  # Handle Authorization
+#### Instance Builder
+When creating an instance, the resource needs to know how to build a new object. If the scope is a descendant of `ActiveRecord::Base`, it will automatically use `scope.new` to build the object.
 
+#### Contexts
+Contexts are memoized blocks of code that are used throughout the request lifecycle of a resource. They can be referenced in [`hooks`](#hooks), [`actions`](#hooks), [`attributes`](#attributes), other [`contexts`](#contexts), etc. A context is defined as follows:
+
+```ruby
+MyCompanyApi.define_resource :users do
+  context :request_method do |context|
+    context.request.request_method
+  end
 end
 ```
 
-### Predefined Contexts
+> **NOTE:** The gem ships with [predefined contexts](#predefined-contexts).
+
+#### Attributes
+Attributes define what fields will appear in the response. Attribute definitions require a name, a type, and a description. In addition, the attribute may include a block that defines how the value is resolved.
+
+```ruby
+MyCompanyApi.define_resource :users do
+  attribute :name, types.String, 'the users name' do |attr_name, instance, context| do
+    instance.public_send(attr_name)
+  end
+end
+```
+
+##### Attribute types
+Attributes require a type that map to JSON types. They are as follows:  
+`types.String`, `types.Boolean`, `types.Integer`, `types.Float`, `types.Array(of: ?)`, `types.Object`
+
+> Array types take an `of` keyword of another type.
 
-#### request_body
-The raw body of the request
+#### Relationships
+Relationships define the way resources reference each other. There are two types of relationships. Relationships behave just like the resource they represent except it's scoped to the parent object. By default the scope of of a relationship resolves to a method equal to the name of the relationship. This can be overridden by passing a `Proc` to the resolve keyword. In addition, the default resource the object resolves to can be specified with the `resource` keyword. If a relationship is given a block it is treated the same as a resource definition, but it's [actions](#actions) are limited by the type of the relationship.
 
-#### request_object
-The JSON parsed into a JSONApionify Structure Object. Keys can be accessed as symbols.
+##### One-to-One
+One-to-One relationships allow a parent resource to reference a single instance of another resource. It is defined as follows:
 
-#### id
-The id present in the request path, if present.
+```ruby
+MyCompanyApi.define_resource :users do
+  relates_to_one :thing, resolve: proc { |rel, instance, context| instance.public_send(rel) } do
+    replace
+  end
+end
+```
+
+##### One-to-Many
+One-to-One relationships allow a parent resource to reference a collection of another resource. It is defined as follows:
+
+```ruby
+MyCompanyApi.define_resource :users do
+  relates_to_many :friends, resource: :users, resolve: proc { |rel, instance, context| instance.public_send(rel) } do
+    add
+    replace
+    remove
+  end
+end
+```
 
-#### request_id
-The id of the requested resource, within the data attribute of the request object.
+#### Actions
+Actions define the routes of a resource and what processing happens when that route is called.
 
-#### request_attributes
-The parsed attributes from the request object. Accessing this context, will also validate the data/structure.
+**Root level resources have the following actions:**
 
-#### request_relationships
-The parsed relationships from the request object. Accessing this context, will also validate the data/structure.
+| Action | Path
+|--------|-----
+| List   | `GET /{resource}`
+| Create | `POST /{resource}`
+| Read   | `GET /{resource}/{id}`
+| Update | `PATCH /{resource}/{id}`
+| Delete | `DELETE /{resource}/{id}`
 
-#### request_instance
-The instance of the object found from the request's data/type and data/id attibutes. This is determined from the resource's defined scope.
+**One-to-Many relationships resources have the following actions:**
 
-#### request_resource
-The resource's scope determined from the request's data/type attribute.
+| Action | Path
+|--------|-----
+| List   | `GET /{resource}/{id}/{relationship}`
+| Create | `POST /{resource}/{id}/{relationship}`
+| Show   | `GET /{resource}/{id}/relationships/{relationship}`
+| Add    | `POST /{resource}/{id}/relationships/{relationship}`
+| Remove | `DELETE /{resource}/{id}/relationships/{relationship}`
+| Replace| `PATCH /{resource}/{id}/relationships/{relationship}`
 
-#### request_data
-The data attribute in the top level object of the request
+**One-to-One relationships resources have the following actions:**
 
-#### authentication
-An object containing the authentication data.
+| Action | Path
+|--------|-----
+| Read   | `GET /{resource}/{id}/{relationship}`
+| Show   | `GET /{resource}/{id}/relationships/{relationship}`
+| Replace| `PATCH /{resource}/{id}/relationships/{relationship}`
 
-#### links
-The links object that will be present in the response.
+#### Hooks
+Hooks can be invoked throughout the request lifecycle. They are defined in the following order:
 
-#### meta
-The meta object that will be present in the response.
+```
+before_request
+  before_{action}
+    before_commit_{action}
+      [commit action]
+    after_commit_{action}
+    before_response
+      [response]
+    after_response
+  after_{action}
+after_request
+```
 
-#### response_object
-The jsonapi object that will be used for the response.
+A hook can be defined on a resource with:
 
-#### response_collection
-The response for the collection.
+```ruby
+MyCompanyApi.define_resource :users do
+  before :create do |context|
+    puts context.request.request_method
+  end
+end
+```
 
+### Predefined Contexts
 
+| Context                 | Description
+|---------                |----------
+| `request`               | The request.  
+| `request_body`          | The raw body of the request.
+| `request_object`        | The JSON parsed into a JSONApionify Structure Object. Keys can be accessed as symbols.
+| `id`                    | The id present in the request path, if present.
+| `request_id`            | The id of the requested resource, within the data attribute of the request object.
+| `request_attributes`    | The parsed attributes from the request object. Accessing this context, will also validate the data/structure.
+| `request_relationships` | The parsed relationships from the request object. Accessing this context, will also validate the data/structure.
+| `request_instance`      | The instance of the object found from the request's data/type and data/id attributes. This is determined from the resource's defined scope.
+| `request_resource`      | The resource's scope determined from the request's data/type attribute.
+| `request_data`          | The data attribute in the top level object of the request
+| `authentication`        | An object containing the authentication data.
+| `links`                 | The links object that will be present in the response.
+| `meta`                  | The meta object that will be present in the response.
+| `response_object`       | The jsonapi object that will be used for the response.
+| `response_collection`   | The response for the collection.
 
 ## Development
 

data/lib/jsonapionify/api/resource/defaults/options.rb

@@ -5,7 +5,7 @@ module JSONAPIonify::Api
       id :id
       scope { self.type.classify.constantize }
       collection do |scope, context|
-        if defined?(ActiveRecord) && scope < ActiveRecord::Base && scope.is_a?(Class)
+        if defined?(ActiveRecord) && scope.is_a?(Class) && scope < ActiveRecord::Base
           scope.all
         else
           scope
@@ -13,7 +13,7 @@ module JSONAPIonify::Api
       end
 
       instance do |scope, key|
-        if defined?(ActiveRecord) && scope < ActiveRecord::Base
+        if defined?(ActiveRecord) && scope.is_a?(Class) && scope < ActiveRecord::Base
           scope.find_by! id_attribute => key
         else
           raise NotImplementedError, 'instance not implemented'
@@ -21,7 +21,7 @@ module JSONAPIonify::Api
       end
 
       new_instance do |scope|
-        if defined?(ActiveRecord) && scope < ActiveRecord::Base
+        if defined?(ActiveRecord) && scope.is_a?(Class) && scope < ActiveRecord::Base
           scope.new
         else
           raise NotImplementedError, 'scope not implemented'

data/lib/jsonapionify/api/resource/includer.rb

@@ -7,7 +7,7 @@ module JSONAPIonify::Api
     included do
       before :list, :create, :read, :update do |context|
         supports_includes = context.root_request? && context.includes.present?
-        is_active_record  = defined?(ActiveRecord) && context.scope.respond_to?(:<) && context.scope < ActiveRecord::Base
+        is_active_record  = defined?(ActiveRecord) && context.scope.is_a?(Class) && context.scope < ActiveRecord::Base
         if supports_includes && is_active_record
           valid_includes = context.includes.select do |k, v|
             context.scope._reflect_on_association(k)

data/lib/jsonapionify/version.rb

@@ -1,3 +1,3 @@
 module JSONAPIonify
-  VERSION = "0.11.9"
+  VERSION = "0.11.10"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapionify
 version: !ruby/object:Gem::Version
-  version: 0.11.9
+  version: 0.11.10
 platform: ruby
 authors:
 - Jason Waldrip
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-15 00:00:00.000000000 Z
+date: 2016-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport