pragma-operation 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3721ff3095c7adde870e9d879340f12d1aed3a90
-  data.tar.gz: 5a10bdd0eaeb67e0a3457fc2881eaef1b01eedcc
+  metadata.gz: 4af59fe5624f0ad6a25a16d2f3a34e6b4b24f7cc
+  data.tar.gz: 385279725b2ebbc9210535c274de95060025a4cd
 SHA512:
-  metadata.gz: dfc63fb63cebc9737babfcdf3ee1bb831911c44460407432d23d3d173fb2f58743bd8cd6f15cf469c1d6b4c746c218a5cdf6e9a14205f1888f5582a01029c87f
-  data.tar.gz: 42b1fca36ece4067a9e31674edacdbf3b0c99560c4088961c990ef82e81f860bfe9f91f7087d47e3edc435dd7b0e5fee8bd6ab3540c284ce8cc002af6671f83a
+  metadata.gz: 11d83a8c30d72bca7e25e86239d6170f6687bdc5113e0a0775feabc979ca9e8e743dbd30af3dc68607a37eb7eaaeb586302b33e641d48ad8359700e23fa614aa
+  data.tar.gz: 3900e69be07c8310c89955a858d100bef14132d47e87cddcd1eab83dc6e70176d152c4a05a568dbf3ccdb178f93b60c2045cddb4956d7ddc526aa93e2d99ed29

data/doc/01-basic-usage.md

@@ -12,10 +12,7 @@ module API
             # The `status` parameter is optional (the default is `:ok`).
             respond_with(
               status: :ok,
-              resource: { pong: params[:pong] },
-              headers: {
-                'X-Ping-Time' => Time.now.to_i
-              }
+              resource: { pong: params[:pong] }
             )
           end
         end
@@ -32,7 +29,6 @@ result = API::V1::Ping::Operation::Create.call(params: { pong: 'HELLO' })
 
 result.status # => :ok
 result.resource # => { pong: 'HELLO' }
-result.headers # => { 'X-Ping-Time' => 1482927872 }
 ```
 
 As you can see, an operation takes parameters as input and responds with:
@@ -62,6 +58,121 @@ Since Pragma::Operation is built on top of [Interactor](https://github.com/colle
 you should consult its documentation for the basic usage of operations; the rest of this section
 only covers the features provided specifically by Pragma::Operation.
 
+## Headers
+
+You can attach headers to your response by manipulating the `headers` hash:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          def call
+            post = ::Post.new(params)
+            post.save!
+
+            headers['X-Post-Id'] = post.id
+
+            respond_with status: :created, resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+You can also set headers when calling `#respond_with`:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          def call
+            post = ::Post.new(params)
+            post.save!
+
+            respond_with status: :created, resource: post, headers: {
+              'X-Post-Id' => post.id
+            }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## HATEOAS
+
+Pragma::Operation supports HATEOAS by allowing you to specify a list of links to use for building
+the `Link` header. You can set the links by manipulating the `links` hash.
+
+For instance, here's how you could link to a post's comments and author:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Show < Pragma::Operation::Base
+          def call
+            post = ::Post.find(params[:id])
+
+            links['comments'] = "/posts/#{post.id}/comments"
+            links['author'] = "/users/#{post.author.id}"
+
+            respond_with resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+You can also set the links when calling `#respond_with`:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Show < Pragma::Operation::Base
+          def call
+            post = ::Post.find(params[:id])
+
+            respond_with resource: post, links: {
+              comments: "/posts/#{post.id}/comments",
+              author: "/users/#{post.author.id}"
+            }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+This will build the `Link` header accordingly:
+
+```ruby
+result = API::V1::Post::Operation::Show.call(params: { id: 1 })
+
+result.status # => :ok
+result.headers
+# => {
+#   'Link' => '</posts/1/comments>; rel="comments",
+#                </users/49>; rel="author"'
+#    }
+```
+
+**Note: Do not set the `Link` header manually, as it will be replaced when building links from the
+`links` hash.**
+
 ## Handling errors
 
 You can use the `#success?` and `#failure?` method to check whether an operation was successful. An

data/lib/pragma/operation/base.rb

@@ -77,6 +77,7 @@ module Pragma
             before :setup_context
             around :handle_halt
             after :mark_result, :consolidate_status, :validate_status, :set_default_status
+            after :build_links
           end
         end
 
@@ -121,19 +122,21 @@ module Pragma
       # method can be called multiple times, overriding the previous context.
       #
       # @param status [Integer|Symbol] an HTTP status code
-      # @param headers [Hash] HTTP headers
       # @param resource [Object] an object responding to +#to_json+
-      def respond_with(status: nil, headers: {}, resource: nil)
-        context.status = status
-        context.headers = headers.to_h
-        context.resource = resource
+      # @param headers [Hash] HTTP headers
+      # @param links [Hash] links to use for building the +Link+ header
+      def respond_with(status: nil, resource: nil, headers: nil, links: nil)
+        context.status = status if status
+        context.resource = resource if resource
+        context.headers = headers if headers
+        context.links = links if links
       end
 
       # Same as {#respond_with}, but also halts the execution of the operation.
       #
       # @see #respond_with
       def respond_with!(*args)
-        respond_with *args
+        respond_with(*args)
         fail Halt
       end
 
@@ -168,6 +171,24 @@ module Pragma
         context.current_user
       end
 
+      # Returns the headers we are responding with.
+      #
+      # This is just a shortcut for +context.headers+.
+      #
+      # @return [Hash]
+      def headers
+        context.headers
+      end
+
+      # Returns the links we are responding with.
+      #
+      # This is just a shotcut for +context.links+.
+      #
+      # @return [Hash]
+      def links
+        context.links
+      end
+
       private
 
       def with_hooks
@@ -187,6 +208,7 @@ module Pragma
       def setup_context
         context.params ||= {}
         context.headers = {}
+        context.links = {}
       end
 
       def handle_halt(interactor)
@@ -219,6 +241,18 @@ module Pragma
         return if /\A(2|3)\d{2}\z/ =~ STATUSES.invert[context.status].to_s
         context.fail!
       end
+
+      def build_links
+        headers.delete('Link')
+
+        link_header = context.links.each_pair.select do |relation, url|
+          url && !url.empty?
+        end.map do |relation, url|
+          %(<#{url}>; rel="#{relation}")
+        end.join(",\n  ")
+
+        headers['Link'] = link_header unless link_header.empty?
+      end
     end
 
     Halt = Class.new(StandardError)

data/lib/pragma/operation/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 module Pragma
   module Operation
-    VERSION = '1.1.1'
+    VERSION = '1.2.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pragma-operation
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Alessandro Desantis