Pragma on Rails
This gem provides Ruby on Rails integration for the Pragma architecture.
Installation
Add this line to your application's Gemfile:
gem 'pragma-rails'
And then execute:
$ bundle
Or install it yourself as:
$ gem install pragma-rails
Usage
Generators
This gem provides a pragma:resource
generator for creating a new resource with the default CRUD
operations:
$ rails g pragma:resource image
create app/resources/api/v1/image
create app/resources/api/v1/image/contract/base.rb
create app/resources/api/v1/image/contract/create.rb
create app/resources/api/v1/image/contract/update.rb
create app/resources/api/v1/image/decorator/instance.rb
create app/resources/api/v1/image/decorator/collection.rb
create app/resources/api/v1/image/operation/create.rb
create app/resources/api/v1/image/operation/destroy.rb
create app/resources/api/v1/image/operation/index.rb
create app/resources/api/v1/image/operation/show.rb
create app/resources/api/v1/image/operation/update.rb
create app/resources/api/v1/image/policy.rb
create app/controllers/api/v1/images_controller.rb
create spec/requests/api/v1/images_spec.rb
route namespace :api do
namespace :v1 do
resources :images, only: %i(index show create update destroy)
end
end
You can also specify an API version (the default is 1):
$ rails g pragma:resource image -v 2
create app/resources/api/v2/image
create app/resources/api/v2/image/contract/base.rb
create app/resources/api/v2/image/contract/create.rb
create app/resources/api/v2/image/contract/update.rb
create app/resources/api/v2/image/decorator.rb
create app/resources/api/v2/image/operation/create.rb
create app/resources/api/v2/image/operation/destroy.rb
create app/resources/api/v2/image/operation/index.rb
create app/resources/api/v2/image/operation/show.rb
create app/resources/api/v2/image/operation/update.rb
create app/resources/api/v2/image/policy.rb
create app/controllers/api/v2/images_controller.rb
create spec/requests/api/v2/images_spec.rb
route namespace :api do
namespace :v2 do
resources :images, only: %i(index show create update destroy)
end
end
Controllers
Pragma::Rails::Controller
gives your controller the ability to run Pragma operations:
module API
module V1
class ArticlesController < ApplicationController
include Pragma::Rails::Controller
def create
run API::V1::Article::Operation::Create
end
end
end
end
In the example above, ArticlesController#create
will run the API::V1::Article::Operation::Create
operation and respond with the status code, headers and resource returned by the operation.
By default, the #params
method will be used as the operation's parameters and #current_user
, if
available, will be used as the operation's user. You can override these defaults by overriding the
#operation_params
and #operation_user
methods in your controller:
module API
module V1
class ArticlesController < ApplicationController
include Pragma::Rails::Controller
def create
run API::V1::Article::Operation::Create
end
private
def operation_params
params.merge(my_additional: 'param')
end
def operation_user
User.authenticate_from params
end
end
end
end
You may also define #policy_context
to pass additional context
to your policies.
Resource Controllers
Resource controllers (provided by the Pragma::Rails::ResourceController
module) abstract even more
of the logic behind your controllers by inferring the operations supported by a resource and
automatically providing controller actions that run them.
With a resource controller, the example above could be rewritten as:
module API
module V1
class ArticlesController < ApplicationController
include Pragma::Rails::ResourceController
private
def operation_params
params.merge(my_additional: 'param')
end
def operation_user
User.authenticate_from params
end
end
end
end
You will still have to define a route to your #create
action, of course, but you don't have to
write the action anymore!
This works with any actions, not only the default CRUD actions defined by Rails. So, for instance,
if you have an API::V1::Article::Operation::Publish
operation, a #publish
action will be
accessible in the API::V1::ArticlesController
controller.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-rails.
License
The gem is available as open source under the terms of the MIT License.