api-extensions 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YjYxMWQxNDgwYmY0YjJmMDY5OGZhMWZkNzdhNmM0NjkwODAzNzZjMg==
+    N2U3NWJjOWY4MWM1OGY2ZDZjMDgwNWJmY2ZkODY2NTU3ZTYzZjQyZg==
   data.tar.gz: !binary |-
-    YzViOWVhNGRkMjljMGI5ODhhZGU1ZjVhMTMwNmNlYWZmOTRhM2RkZQ==
+    OTJiZmZmOTI2NmU1ZTgyNjg5ODk4OGIxMzc1YzVkZDM2ZWQyY2I4Yw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    ZjA0NDk1M2VkMGI0YmE4MzFkY2RlYTQzN2IzZWRhNjljNzkxYThmNzgzODBi
-    MWMyOWIwYzBjMzhmYjRjMzIwZWQ5MGMyMDU4ZTdhODJkMDc4ZjQ4MTgyZjVj
-    YjNjZDIwMjg5ZTc1NjM2MDUzZDQxMWUyNzBmMzU2ZjhkMGQyYmU=
+    ZDY3NGM1MmU0MDRkNjQyM2FkY2FjNTc2MmI1YTA0OGJkOTM0MWIzZTc0MThm
+    YmM1YTAxMWUxZTdlNjE1OWJjNDFkNmJjZjczOGQ5ZDQyOWZlYzkxMWZkM2Rj
+    ODU1ZWFlMTRmZjY0YzllYTIxYTFlYTFlMjAwMTUxYWIzMDc0MWQ=
   data.tar.gz: !binary |-
-    ZDYxZDQxMWFkODg0NzEwZjI1NmY0NzYzMjllNjBlOTAxNDAxN2UzMDkzMjhl
-    NGI0ZjE2NzA1NGY4MmExMDNlYTJjOWM0NWY0NTdhMTg2ZTU5OWUyZWM3ZjIz
-    NDBjNmRjODdmZGZhZmU3ZDY3YTIwMDU3YjRhZGI3MWJkYWQ2NGM=
+    YWY5MWI3MTAwZjNiYWU2NmM0ODRkZmRmZjMxMmQzYjExNmY0ZGUyNjY0MGI5
+    ZDdhYzUyYThmODA2ZmJjNThkOTI4MTRjYTVjNWQ2Yzk5ZmZlZWUyMjI3OTI1
+    NDhjOGRiNjJiYmQ2M2QwNTY1NTQ4NGY1MTk5NzcwYzY0NGI5M2Q=

data/README.md

@@ -23,6 +23,32 @@ Or install it yourself as:
 
 ## Usage
 
+### `expand` extension
+
+The behavior of this extension is best described at
+[the api-doc repo](https://github.com/ncuesta/api-doc/blob/master/README.en.md#links-expansion).
+
+By including the `Api::Extensions::Expand` module in any class, you will get a `process_expand`
+method that will handle the expansion of linked resources - as described in the linked document.
+
+Please note that this extension **requires that the including class responds to a `get` method**.
+
+```ruby
+require 'api/extensions/expand'
+
+class MyApiHandler
+
+  def initialize
+    include Api::Extensions::Expand
+  end
+
+  def handle(request)
+    response = fiddle_with request
+    process_expand request[:expand], response
+  end
+end
+```
+
 ### `fields` extension
 
 The behavior of this extension is best described at
@@ -44,6 +70,13 @@ class MyApiHandler
 end
 ```
 
+## Running tests
+
+The test suite uses Cucumber, and can be run through `rake`:
+
+```bash
+$ rake features
+```
 
 ## Contributing
 

data/features/expand.feature

@@ -0,0 +1,42 @@
+Feature: Expand functional extension
+  In order to reduce the amount of requests sent to the API
+  As a client application
+  I want to be able to specify which related links I need expanded
+
+  Scenario Outline: Invalid expand values are ignored
+    Given I get a request for resource "/articles/1.json"
+    And I get the expand parameter "<value>"
+    When I process the expand parameter
+    Then the resulting response should be the same as the original one
+
+    Examples:
+      | value            |
+      |                  |
+      | ,                |
+      | ,,               |
+      | non-existing-key |
+      | non,existing,key |
+      | non(existing)    |
+
+
+  Scenario Outline: Links expansion for singular documents
+    Given I get a request for resource "/articles/1.json"
+    And I get the expand parameter "<value>"
+    When I process the expand parameter
+    Then the resulting response should include the original response
+    And the resulting response should also contain "<expanded_links>" as new attributes
+
+  Examples:
+    | value                         | expanded_links |
+    | title                         | title          |
+    | title,name                    | title,name     |
+    | title,name,                   | title,name     |
+    | title,name,non_existent_field | title,name     |
+
+
+  Scenario: Links expansion for collective documents
+    Given I get a request for resource "/articles.json"
+    And I get the expand parameter "entries(self)"
+    When I process the expand parameter
+    Then the resulting response should include the original response
+    And the resulting response should have the entries expanded

data/features/step_definitions/common_steps.rb

@@ -12,6 +12,21 @@ def resources
         'self' => { 'href' => '/link/to/self' },
         'other' => { 'href' => '/link/to/other' }
       }
+    },
+    '/articles.json' => {
+      'entries' => [
+        {
+          'links' => {
+            'self' => { 'href' => '/articles/1.json' }
+          }
+        }
+      ],
+      'total'   => 1,
+      'limit'   => 10,
+      'offset'  => 0,
+      'links'   => {
+        'self' => { 'href' => '/link/to/self' }
+      }
     }
   }
 end

data/features/step_definitions/expand_steps.rb

@@ -0,0 +1,31 @@
+require 'api/extensions/expand'
+
+Before do
+  @expand_processor = Object.new
+  class << @expand_processor
+    def get url
+    end
+
+    include(Api::Extensions::Expand)
+  end
+end
+
+Given(/^I get the expand parameter "(.*)"$/) do |value|
+  @expand = value
+end
+
+When(/^I process the expand parameter$/) do
+  @result = @expand_processor.process_expand @expand, @response
+end
+
+Then(/^the resulting response should include the original response$/) do
+  pending # express the regexp above with the code you wish you had
+end
+
+Then(/^the resulting response should also contain "(.*?)" as new attributes$/) do |arg1|
+  pending # express the regexp above with the code you wish you had
+end
+
+Then(/^the resulting response should have the entries expanded$/) do
+  pending # express the regexp above with the code you wish you had
+end

data/features/step_definitions/fields_steps.rb

@@ -1,8 +1,8 @@
 require 'api/extensions/fields'
 
 Before do
-  @processor = Object.new
-  class << @processor
+  @fields_processor = Object.new
+  class << @fields_processor
     include(Api::Extensions::Fields)
   end
 end
@@ -17,7 +17,7 @@ Given /^I get the fields parameter "(.*)"$/ do |value|
 end
 
 When /^I process the fields parameter$/ do
-  @result = @processor.process_fields @fields, @response, @request_path
+  @result = @fields_processor.process_fields @fields, @response, @request_path
 end
 
 Then /^the resulting response should include the required fields$/ do

data/lib/api/extensions/expand.rb

@@ -0,0 +1,61 @@
+#
+# Expand extension
+#
+# https://github.com/ncuesta/api-doc/blob/master/README.en.md#links-expansion
+#
+module Api
+  module Extensions
+    module Expand
+      # Check requirements on inclusion
+      def self.included(base)
+        raise ::Exception.new('Base class must implement a :get method to include the ExpandProcessor module') unless base.method_defined?(:get)
+      end
+
+      # Process the expand functional extension
+      def process_expand(keys, scope)
+        keys.split(',').each do |key|
+          entries_parts = key.match(/entries\((.*)\)$/)
+
+          if entries_parts && scope['entries']
+            # (2) Collective key: expand=entries(self)
+            scope['entries'].collect! { |entry| process_expand entries_parts[1], entry }
+          else
+            recursive = key.match(/([^\(]+)\((.*)\)$/)
+
+            if recursive
+              # (1) Recursive key: expand=section(parent)
+              local_key, sub_key = recursive[1, 2]
+              # Expand the local key
+              scope = expand scope, local_key
+              # Recursively expand the remaining keys - if possible
+              new_scope = local_key == 'self' ? scope : scope[local_key]
+              process_expand(sub_key, new_scope) if new_scope
+            else
+              # (0) Simple key: expand=section
+              scope = expand scope, key
+            end
+          end
+        end
+
+        scope
+      end
+
+      # Actually expand a link
+      def expand(resource, link)
+        if resource['links'].include?(link)
+          sub_resource_uri = resource['links'][link]['href']
+          sub_resource     = get sub_resource_uri
+
+          # 'self' links replace the original resource
+          if link == 'self'
+            resource = sub_resource
+          else
+            resource[link] = sub_resource
+          end
+        end
+
+        resource
+      end
+    end
+  end
+end

data/lib/api/extensions/version.rb

@@ -1,5 +1,5 @@
 module Api
   module Extensions
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

data/lib/api/extensions.rb

@@ -1,3 +1,4 @@
+require 'api/extensions/expand'
 require 'api/extensions/fields'
 require 'api/extensions/version'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Nahuel Cuesta Luengo
@@ -81,10 +81,13 @@ files:
 - Rakefile
 - api-extensions.gemspec
 - cucumber.yml
+- features/expand.feature
 - features/fields.feature
 - features/step_definitions/common_steps.rb
+- features/step_definitions/expand_steps.rb
 - features/step_definitions/fields_steps.rb
 - lib/api/extensions.rb
+- lib/api/extensions/expand.rb
 - lib/api/extensions/fields.rb
 - lib/api/extensions/version.rb
 homepage: https://github.com/ncuesta/api-extensions
@@ -112,6 +115,8 @@ signing_key:
 specification_version: 4
 summary: A collection of extensions for Hypermedia-driven APIs
 test_files:
+- features/expand.feature
 - features/fields.feature
 - features/step_definitions/common_steps.rb
+- features/step_definitions/expand_steps.rb
 - features/step_definitions/fields_steps.rb