Pragma on Rails
This gem provides Ruby on Rails integration for the Pragma architecture.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install pragma-rails
This gem provides a
pragma:resource generator for creating a new resource with the default CRUD
$ 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
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
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
available, will be used as the operation's user. You can override these defaults by overriding the
#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 (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
Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-rails.
The gem is available as open source under the terms of the MIT License.