Pragma::Operation

Operations encapsulate the business logic of your JSON API.

They are built on top of the Trailblazer::Operation gem.

Installation

Add this line to your application's Gemfile:

gem 'pragma-operation'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pragma-operation

Usage

Let's build your first operation!

module API
  module V1
    module Article
      class Show < Pragma::Operation::Base
        step :find!
        failure :handle_not_found!, fail_fast: true
        step :authorize!
        failure :handle_unauthorized!
        step :respond!

        def find!(params:, **options)
          options['model'] = ::Article.find_by(id: params[:id])
        end

        def handle_not_found!(options)
          options['result.response'] = Pragma::Operation::Response::NotFound.new
          false
        end

        def authorize!(options)
          options['result.authorization'] = options['model'].published? || 
            options['model'].author == options['current_user']
        end

        def handle_unauthorized!(options)
          options['result.response'] = Pragma::Operation::Response::Forbidden.new(
            entity: Error.new(
              error_type: :forbidden,
              error_message: 'You can only access an article if published or authored by you.'
            )
          )
        end
  
        def respond!(options)
          options['result.response'] = Pragma::Operation::Response::Ok.new(
            entity: options['model'].as_json
          )
        end
      end
    end
  end
end

Yes, I know. This does not make any sense yet. Before continuing, I encourage you to read (and understand!) the documentation of Trailblazer::Operation. Pragma::Operation is simply an extension of its TRB counterpart. For the rest of this guide, we will assume you have a good understanding of TRB concepts like flow control and macros.

Response basics

The only requirement for a Pragma operation is that it sets a result.response key in the options hash by the end of its execution. This is a Pragma::Operation::Response object that will be used by pragma-rails or another integration to respond with the proper HTTP information.

Responses have, just as you'd expect, a status, headers and body. You can manipulate them by using the status, headers and entity parameters of the initializer:

response = Pragma::Operation::Response.new(
  status: 201,
  headers: {
    'X-Api-Custom' => 'Value'
  },
  entity: my_model
)

You can also set these properties through their accessors after instantiating the response:

# You can set the status as a symbol:
response.status = :created

# You can set it as an HTTP status code:
response.status = 201

# You can manipulate headers:
response.headers['X-Api-Custom'] = 'Value'

# You can manipulate the entity:
response.entity = my_model

# The entity can be any object responding to #to_json:
response.entity = {
  foo: :bar
}

Decorating entities

The response class also has support for Pragma decorators.

If you use decorators, you can set a decorator as the entity or you can use the #decorate_with convenience method to decorate the existing entity:

response.entity = ArticleDecorator.new(article)

# This is equivalent to the above:
response.entity = article
response.decorate_with(ArticleDecorator) # returns the response itself for chaining

Errors

Pragma::Operation ships with an Error data structure that's simply the recommended way to present your errors. You can build your custom error by creating a new instance of it and specify a machine-readable error type and a human-readable error message:

error = Pragma::Operation::Error.new(
  error_type: :invalid_date,
  error_message: 'You have specified an invalid date in your request.'
)

error.as_json # => {:error_type=>:invalid_date, :error_message=>"You have specified an invalid date in your request.", :meta=>{}}
error.to_json # => {"error_type":"invalid_date","error_message":"You have specified an invalid date in your request.","meta":{}}

Do you see that meta property in the JSON representation of the error? You can use it to include additional metadata about the error. This is especially useful, for instance, with validation errors as you can include the exact fields and validation messages (which is exactly what Pragma does by default, by the way):

error = Pragma::Operation::Error.new(
  error_type: :invalid_date,
  error_message: 'You have specified an invalid date in your request.',
  meta: {
    expected_format: 'YYYY-MM-DD'
  }
)

error.as_json # => {:error_type=>:invalid_date, :error_message=>"You have specified an invalid date in your request.", :meta=>{:expected_format=>"YYYY-MM-DD"}}
error.to_json # => {"error_type":"invalid_date","error_message":"You have specified an invalid date in your request.","meta":{"expected_format":"YYYY-MM-DD"}}

If you don't want to go with this format, you are free to implement your own error class, but it is not recommended, as the built-in macros will use Pragma::Operation::Error.

Built-in responses

Last but not least, as you have seen in the example operation, Pragma provides some built-in responses for common status codes and bodies. Some of these only have a status code while others (the error responses) also have a default entity attached to them. For instance, you can use Pragma::Operation::Response::Forbidden without specifying your own error type and message:

response = Pragma::Operation::Response::Forbidden.new

response.status # => 403
response.entity.to_json # => {"error_type":"forbidden","error_message":"You are not authorized to access the requested resource.","meta":{}}

The built-in responses are not meant to be comprehensive and you will most likely have to implement your own. If you write some that you think could be useful, feel free to open a PR!

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-operation.

License

The gem is available as open source under the terms of the MIT License.