Service objects (sometimes referred to as services) is a holy grail in Ruby On Rails development that helps to decompose your fat ActiveRecord models and keep your controllers slim and readable. When and how to use Service Objects? Learn more in Essential Ruby On Rails Patterns!

Essential Ruby On Rails Patterns

I help our CTOs, Development Leads, Product Owners and business executives to design and build scalable and maintainable systems. With over 13 years of experience gained on software development projects delivered to international clients, I am able to enhance the productivity of software development teams while creating data collection, processing and analysis tools.

Błażej Kosmowski

Service objects (sometimes referred to as _services_) is a holy grail in Ruby On Rails development that helps to [decompose your fat ActiveRecord models](http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/) and keep your controllers slim and readable.

When to use Service Objects?
The pattern is so simple and powerful that it may become a bit overused in time; it is particularly useful when we need a place to define complex actions, processes with many steps, callbacks or interactions with multiple models which do not fit anywhere else. Service objects are also commonly used to mitigate problems with model callbacks that interact with external classes ([read more…](http://samuelmullen.com/2013/05/the-problem-with-rails-callbacks/)).

### How to get most out of Service Object pattern?
#### 1. Stick to one naming convention
One of the most difficult tasks in programming is assigning things proper, self-explanatory names. There is a popular way to name service objects with words ending with “or”, i.e. `UserCreator`, `TwitterAuthenticator`, `CodeObfuscator`, etc. Sometimes such names may become a bit awkward, i.e., `OrderCompleter`. Therefore, I find naming service objects after commands or actions a bit more comprehensible. `CreateUser`, `AuthenticateUsingTwitter`, `ObfuscateCode`, `CompleteOrder` — it is clear what a given service object is responsible for. Regardless, try not to mix multiple naming conventions if you start using one. Be consistent.

#### 2. Do not instantiate service objects directly
We usually do not have much use for a service object instance other than just for executing a `call` method on it. If this is the case, consider using the following abstraction to shorten a notation of calling service objects:

```
module Callable
  extend ActiveSupport::Concern
  class_methods do
    def call(*args)
      new(*args).call
    end
  end
end
```

Including this module will allow you to simplify the `CreateUser.new(params).call` or `CreateUser.new.call(params)` notations into `CreateUser.call(params)`. It is shorter and more readable. Still it leaves an option to instantiate the service object, which might be useful when we need to retrieve its internal state.

#### 3. Stick to one way of calling service objects
While I personally like using the `call` method, there is no particular reason not to use a different one (`perform`, `run` or `execute` are also good candidates). It is important though to always do it the same way, as our class name already states what the class responsibility is — there is no need to make it even more clear. The approach will relieve you from a burden of thinking about the right name every time you implement a new service object and will also be clear for other programmers how to use service object even without having a peek inside its implementation.

#### 4. Keep one responsibility per service object
This rule is somehow enforced by sticking to one way of calling a service object, yet it is not impossible to sneak in multiple responsibilities in such service objects as well. While service objects excel in orchestrating multiple actions, we should ensure that only one set of such actions is executed. An anti-pattern here might be to introduce e.g. the `ManageUser` service object, which would be responsible for creating and deleting users. Firstly, “Manage” does not say much; it is also not clear how to control which action should be executed. Introducing `DeleteUser` and `CreateUser` services instead makes the whole thing more readable and natural.

#### 5. Keep service objects constructors simple
It is a good idea to keep constructors simple in most of the classes we implement. Still, when our primary way of calling services is through the call class method, it might be even more beneficial to make constructor responsible for only saving arguments in service instance variables.

```
class DeleteUser
  include Callable
  def initialize(user_id:)
    @user = User.find(user_id)
  end
  
  def call
    #…
  end
end
```

versus

```
class DeleteUser
  include Callable  
  
  def initialize(user_id:)
    @user_id = user_id
  end
  def call
    #…
  end
  private
  attr_reader :user_id
  def user
    @user ||= User.find(user_id)
  end
end
```

Not only can we focus on testing the call method rather than the constructor, but we can also draw a clear line between what can live in the constructor and what cannot do so. As developers we have to make a number of decisions everyday, why not take one off our plate by standardizing our approach.

#### 6. Keep the arguments of call methods simple
If more than one argument is provided to the service object, it might be reasonable to consider introducing keywords arguments to make those arguments more comprehensive. Even if service object accepts one argument only, using keyword argument might make it more readable as well, e.g.

```
UpdateUser.call(params[:user], false)
```

versus

```
UpdateUser.call(attributes: params[:user], send_notification: false)
```

#### 7. Return results through state readers
You will seldom need to retrieve information from your service objects. In case you needed to do so, there are a couple of ways you can approach this problem. A service object might return the result from its call method — for instance, returning `true` would indicate successful execution, while returning `false `would indicate failure. On the other hand, you create much more flexible solution when you make the call method return the service object itself. This way we can take advantage of reading service object instance state , e.g.

```
update_user = UpdateUser.call(attributes: params[:user])
unless update_user.success?
  puts update_user.errors.inspect
end
```

In some cases it is more effective to communicate edge cases which are unlikely to happen by raising exceptions instead, e.g.

```
begin
  UpdateUser.call(attributes: params[:user])
rescue UpdateUser::UserDoesNotExistException
  puts “User does not exist!”
end
```

#### 8. Focus on readability of your call method
The `call` method is the heart of your service object. It is a good practice to focus on making it as readable as possible — preferably just by describing the steps involved and reducing extra logic to the minimum. As an option, we can also control the flow of particular steps using `and` and `or` e.g.

```
class DeleteUser
  #…
  def call
    delete_user_comments
    delete_user and 
      send_user_deletion_notification
  end
private
  #…
end
```

#### 9. Consider wrapping call methods in transactions
Sometimes when multiple steps are involved to fulfill the responsibility of a service object, it might be a good idea to wrap the steps in a transaction, so that if any of the steps fails, we can always rollback the changes made in previous steps.

#### 10. Group service objects in namespaces
Sooner or later we will end up with tens of service objects. To improve code organization it is a good practice to group common service objects into namespaces. Those namespaces can group service objects by external services, high-level features or any other dimension we can think of. Still we need to keep in mind that the primary goal is to keep service object names and locations straightforward and readable. Sticking to one convention will allow you to quickly decide on the appropriate location — in this case leaving yourself fewer choices is a good thing.

### Summary
A service object is a simple and powerful pattern which is easy to test and which has a wide area of use. The ease of implementing it is also a threat to keeping its implementation under control. Using concise convention when naming service objects, calling and getting results out of them consistently in the same way as well as keeping internals of service object classes simple and readable will ensure that your codebase will benefit from this pattern to a great extent.

If you feel you might need some simple abstraction around service object pattern, consider trying the [BusinessProcess](https://github.com/Selleo/business_process) gem or consider a very similar [Use Case](https://webuild.envato.com/blog/a-case-for-use-cases/) pattern. An even thinner layer is provided by the [rails-patterns gem](https://github.com/Selleo/pattern).



Service objects (sometimes referred to as services) is a holy grail in Ruby On Rails development that helps to decompose your fat ActiveRecord models and keep your controllers slim and readable.

Essential RubyOnRails Patterns — Part 1: Service Objects

Query Objects (also referred to as queries) is another pattern that helps in [decomposing your fat ActiveRecord models](http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/) and keeping your code both slim and readable. While this article is written with Ruby On Rails in mind, it easily applies to other frameworks, especially MVC based and applying `ActiveRecord` pattern.

### When to use Query Objects?
One should consider using query objects pattern when in need of performing complex queries on `ActiveRecord` relation. Usually using scopes for such purposes is not recommended. As a rule of thumb, if scope interacts with more than one column and/or joins in other tables, it should be considered to be moved to query object — as a side-effect we can limit amount of scopes defined in our models to a necessary minimum. Also whenever a chain of scopes is to be dealt with, using query object as well should be considered. ([read more…](http://craftingruby.com/posts/2015/06/24/say-no-to_chained-scopes.html)).

### How to make most out of Query Object pattern?
#### 1. Stick to one naming convention
To make inventing query object class name easier, we may establish some base rules that we will then follow. One idea is to always suffix query object name with `Query`, so we are constantly aware we’re dealing with query, and not `ActiveRecord` descendant. Another idea is to always use pluralized name of a model, a given query is designed to work with. This way it will be clear for us, that i.e. `RecentProjectUsersQuery` will return a users’ relation when called. Whatever approach we choose to apply, most of the time it is beneficial to stick to one way of naming classes of given pattern, as it tends to reduce confusion whenever we need to introduce a new class.

#### 2. Use .call method returning a relation to call query objects
In contrast to service objects, where we have some level of freedom in naming the method dedicated to use a service object, in order to make the most out of query object pattern in rails, we should implement `.call` method that returns a relation object. If we follow this rule, such query objects can be easily used to construct scopes if required. ([read more…](http://craftingruby.com/posts/2015/06/29/query-objects-through-scopes.html)

#### 3. Always accept relation like object as first argument
It is a good practice to accept a relation as a first argument when calling query objects we introduce. Not only is this required when using query objects as scopes (see recommendation above) but also this way we can make our query objects chainable, which gives us an additional level of flexibility. To keep the ease of use intact, make sure to provide a default entry relation, so such query object can be used without providing an argument. It is also important to always return relation from query object with the same subject (table) as the relation query object was provided with.

#### 4. Provide a way to accept extra options
While sometimes such necessity can be avoided by subclassing the existing or introducing the new query objects, sooner or later we will need to accept some extra options to query object we’ve introduced. This can be used to customize the logic of how given query object returns its results, that may effectively turn such query object into a flexible filter. To maintain good level of readability it is recommended to only pass such options as hash / keyword arguments and always provide default values.

#### 5. Focus on readability of your querying method
Regardless of whether we decide to store the core logic of our query in the `.call` method itself or any other method of our query object, we should make it as readable as possible. This will be the first place other developers will look into to find out what such query object is about, so this little extra effort may make their lives easier.

#### 6. Group query objects in namespaces
Depending on complexity of our project and to what extent it takes advantage of `ActiveRecord`, we may end up with quite a lot of query objects. To arrange our code better it is a good practice to group similar query objects into namespaces. One idea on grouping is to use name of model those queries deal with, but it can be anything reasonable. As usual, by sticking to one way of grouping query objects, it will be easy for us to decide on appropriate location for such class once we introduce a new one. Storing all of our query objects in `app/queries` is also recommended.

#### 7. Consider delegating all methods to result of `.call`
One might consider implementing method_missing for query object to delegate all methods to the result of `.call` method. This way a query object could be used just as a regular relation — i.e. `RecentProjectUsersQuery.where(first_name: “Tony”`) instead of `RecentProjectUsersQuery.call.where(first_name: “Tony”)`. However, as with any case of metaprogramming, following this approach should be a conscious and justified decision.

Summary
A query object is a simple, easily testable pattern that helps in abstracting queries, relations and scope chains with complex implementation. By following a few simple rules outlined above, we can make sure that this pattern remains readable, flexible and easy to use not only for us, but, first of all, for others who might work with our code in the future. An example below presents one way of implementing such object.

```
module Users
  class WithRecentlyCreatedProjectQuery
    DEFAULT_RANGE = 2.days

    def self.call(relation = User.all, time_range: DEFAULT_RANGE)
      relation.
        joins(:projects).
        where('projects.created_at > ?', time_range.ago).
        distinct
    end
  end
end
```

If you feel you might need some simple abstraction around query object pattern, consider using thin wrapper provided by the [rails-patterns](https://github.com/Selleo/pattern) gem.

Query Objects (also referred to as queries) is another pattern that helps in decomposing your fat ActiveRecord models and keeping your code both slim and readable. While this article is written with Ruby On Rails in mind, it easily applies to other frameworks, especially MVC based and applying ActiveRecord pattern.

Essential RubyOnRails Patterns — Part 2: Query Objects

Clients and Wrappers (also referred to as [“Facades”](https://en.wikipedia.org/wiki/Facade_pattern)) are remarkably useful tools for working with external services, libraries or APIs. While both Clients and Wrappers are primarily used to facilitate usage of before-mentioned libraries or APIs, there are some significant differences in responsibilities each of these patterns have. In some cases a Wrapper can take over a Client’s responsibilities too.

### When to use Clients ?
Clients are best suited for handling an external or internal services API — be it for JSON API, GraphQL, SOAP or any other custom format or protocol. Instead of communicating with such service using low level libraries directly, (i.e. [Faraday](https://github.com/lostisland/faraday) or [HTTParty](https://github.com/jnunemaker/httparty)) we do provide a thin interface around it in the form of a Client.

### When to use Wrappers ?
Wrappers (Facades) work best as a layer encapsulating other library with complex interface or the one that is not very expressive, especially in the domain of our application. Wrappers are also very useful whenever default responses provided by aforementioned libraries are not very useful for us in their original form.

### How to make most out of Client pattern?
#### 1. Methods should reflect wrapped endpoints
If API we provide abstraction over exposes `/getNewProducts` endpoint, then our Client should resemble it by exposing `get_new_products` method. It is also a good idea to accept as many arguments to such method as original endpoint handles. In general, each Client method should allow as many capabilities of wrapped endpoint as reasonable.

#### 2. Results should reflect responses of wrapped endpoints
Similarly to the previous rule, the results we return from methods wrapping external endpoint should resemble what this endpoint returns. It is ok to perform some lightweight transformations like JSON parsing or changing hash keys from camelized to underscored, but we should be cautious with adding any additional logic.

#### 3. Provide references to wrapped endpoint
It might be good to provide a quick reference to documentation of wrapped endpoint above each methods that handles it. This way a user of such method can quickly review its specification and obtain information about potential capabilities (i.e. ways to filter results).

#### 4. Provide expressive naming for Client classes
It is good convention to include name of service or API being wrapped in the class name. Also suffixing such class with `Client` will clearly show what the responsibility of this class is. `TwitterClient` or `AirbnbClient` are examples of good Client class names.

#### 5. Keep Clients isolated from your main app
Treat Clients as something that can be shared with different app without any additional effort. This basically means, that Clients should possess zero knowledge about the app itself and serve only as an interface to the external resources.

#### 6. Provide an instance Client users can work with
As it is not uncommon to work with multiple Client methods simultaneously, refrain yourself from implementing those methods as static. For most of the time using an external service is correlated with performing some kind of authentication. Allowing users to instantiate a Client will make it possible to share authenticated session between multiple calls.

#### 7. Do not reinvent the wheel
Last but not least, before implementing a Client, make sure that there is no existing library already providing a Client for given service. Most of popular services have Clients for various programming languages available and ready to use.

### How to make most out of Wrapper pattern?
#### 1. Prefer wrapping other libraries
While Wrappers can sort of replace Clients in cases we need one or two endpoints handled, it is usually a better idea to keep Wrapper’s and Client’s logic separate. A rule of a thumb here is to think about Wrapper as an encapsulation of other library to facilitate interaction with this library, making it more expressive and better suited for our purposes. For instance, when writing tests it is much easier to mock something like `S3Wrapper.get_file(“file_identifier”)` instead of investigating which Client to choose and how to use it. This will need to happen anyway when writing Wrapper tests, but such approach works great when proceeding with Behavior Driven Development.

#### 2. Provide expressive naming for public methods
In Client’s case it was important to keep naming of public interface methods as similar to handled endpoints as possible. For Wrappers it is the opposite — naming should reflect our needs and be as meaningful as possible, with the list of easy to understand arguments. In fact this is the main responsibility of Wrappers — simplification of interfaces.

#### 3. Provide expressive naming for wrapper classes
Just as in case of Clients, it is good convention to include names of libraries or services being wrapped in the Wrapper’s class name and suffixing it with `Wrapper`. Some adequate names would be `ElasticSearchWrapper` or `S3Wrapper`. Another option is to use namespacing, i.e. `S3::Wrapper` if we need a place for more classes correlated with wrapper, yet we need to be cautious not to get into naming-conflict with a library being wrapped.

#### 4. Prefer using static methods
As Wrapper tends to be use-and-forget kind of tool it is a good idea to expose its capabilities as static methods. `S3Wrapper.new.get_file(file_identifier)` can usually be easily replaced with `S3Wrapper.get_file(file_identifier)`. If we internally still want to work with an instance, we can use Singleton pattern to make our life easier (even though “Singleton” and “Easy life” can be rarely seen together in same sentence) and then delegate exposed methods to singleton’s instance on class level.

#### 5. Design responses in the useful way
In opposition to Clients, where responses were to reflect actual responses from service being handled as closely as possible, Wrappers should return responses as close to our needs as possible. Any kind of data formatting or transformations can happen at this point. Thanks to that, when writing higher level tests, we can plan our solution using the data structures we feel the most comfortable working with.

#### 6. Keep Wrappers isolated from your main app
Even though Wrappers are to be designed to simplify interfaces of other services / libraries and return highly usable responses, don’t yield to temptation of leaking your app details into Wrapper’s implementation (i.e. using models that are outside of Wrapper’s scope). If it happens incidentally, we can probably live with that, but it is better to follow the rule of not allowing that at all. Not introducing such dependencies will render wrappers more dependable upon.

### Summary
If we ever need to simplify the use of any kind of library, be it for improving decomposition, testability or purely for making nice, readable API, Wrappers can help a lot in that effort. If it happens that there are no dedicated libraries for services we integrate with, Wrappers paired with Clients can be a great addition to our toolbox that will facilitate working with such services.

Below you can find an example of super simple Client and Wrapper encapsulating [OMDB API](http://www.omdbapi.com/). When done with it, consider having a look at [part 4 — Form Objects](https://medium.com/@blazejkosmowski/essential-rubyonrails-patterns-form-objects-b199aada6ec9).

<Gist id="002a2803bd43d9f544b25eb907dd9d20" />

Clients and Wrappers (also referred to as “Facades”) are remarkably useful tools for working with external services, libraries or APIs. While both Clients and Wrappers are primarily used to facilitate usage of before-mentioned libraries or APIs, there are some significant differences in responsibilities each of these patterns have. In some cases a Wrapper can take over a Client’s responsibilities too

Essential RubyOnRails Patterns — Part 3: Clients And Wrappers

Form Object is a very useful pattern in [rails](http://rubyonrails.org/) ecosystem as it can address variety of issues and antipatterns. In this article we will attempt to sort out in which situations Form Objects can prove useful and what conventions allow us to make most out of them.



### When to use Form Objects?

### Replacement for Strong Parameters

I am not a huge fan of strong parameters in rails and therefore I do enjoy what Form Object brings to the table. As each Form Object has all of its attributes explicitly defined, we can be sure, that no extra attributes will be persisted in case of parameter tampering.



What is more, we have full freedom of adding any kind of attributes using any technique (i.e. using [Virtus](https://github.com/solnic/virtus)), so we can take advantage of attributes coercion, default values or virtual attributes with little to no effort.



### A good place for model lifecycle callbacks

We should always be cautious when adding callbacks to our models, due to the [variety of reasons](http://samuelmullen.com/2013/05/the-problem-with-rails-callbacks/). If we are determined to move the callback logic outside of a model, we obviously need to decide, where to move this logic to. This is where Form Objects can usually help. While callbacks related to destroying a record will fit better in [service objects](https://medium.com/selleo/essential-rubyonrails-patterns-part-1-service-objects-1af9f9573ca1), those related to creation and validation of record can be easily placed in persistence logic of a Form Object.



### Form Object as virtual resource

Form Object does not necessarily need to map 1 to 1 with a model. Not only can we use a different set of attributes but we may also decide not to represent any model at all. A good example would be a contact form — if we decide not to store a message sent in database, our persistence logic can focus only on scheduling email delivery, while the Form Object will help by facilitating rendering of the actual form in UI.



### Form Object as composed resource

If you need one form to save data into multiple models, then you have quite a few techniques available. [Rails Nested Attributes](http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html) is one of them, but it requires us to carefully construct attribute names. This usually does not play nice with forms generated by frontend frameworks without burdensome configuration. We can handle all the logic in a controller, but it just does not feel right to increase its complexity. Service objects may help, still usually it might feel awkward to create a service responsible solely for persisting data.



Form Objects are a good fit here. Not only are we not limited to any specific attribute names but we can also fully and explicitly control the logic of creating data in multiple tables. Finally, forms are designed for saving stuff, so using them just feels right.



### Form Object as options provider

Sooner or later our forms, as seen from UX perspective, will need some dropdowns representing options available. Be it the list of groups we want to associate the user with. The usual question is where to put logic responsible for generating this list of options. One way to go is to include it directly in template — it is not recommended to include any complex logic within view layer though, especially if data retrieved bypasses a controller. Using helpers is another obvious choice, but exposing something very specific this way just does not seem right — what is more, we cannot influence the logic of such helper without passing some extra arguments into it.



Form Objects seem to be a perfect solution here. We not only have a dedicated place for this kind of code, that is easily testable and we can affect the logic using form’s internal state, but also it just feels right to have code so closely correlated with the form in the form itself.



### How to make most out of Form Object pattern?

**\#1 Stick to one naming convention**

Rule applicable to almost any pattern. In case of Form Objects it feels reasonable to suffix such classes with `Form`, to help differentiate forms from models. If a form maps to a single model, including this model’s name in form name also seems to be a good idea. In other cases we should go after making the name as expressive as possible. `RegistrationForm` or `UserSettingsForm` sound like good examples of such expressiveness.



**\#2 Implement #save and #save!**

It appears to be a good idea not to differentiate form’s API to much from model’s API. This will make using forms natural and easy to work with. Therefore, to trigger form’s persistence logic we should use `save` method or its exception-raising brother `save!`.



**\#3 Provide validations capability**

As a follow-up to previous point, it might be beneficial to include [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) in our form objects to enable validation capabilities on all attributes. It is worth mentioning that not all validations will work out of the box — a good example here is uniqueness validation that depends heavily on model’s API and needs to be handled in a custom way in form objects (at least without providing complex logic that would enable such validation to work with forms properly).



**\#4 Implement #param_key**

In order to facilitate ease of use of forms any further, we should provide implementation of `param_key` and potentially `model_name` methods. This will allow us to pass form objects directly as [`form_for`](http://edgeapi.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_for) helper argument without any extra logic. Most of ready-to-use abstractions of form object have this capability built-in.



**\#5 Keep persistence logic in one place**

Similarly to service object’s `call` method, it is a good convention to keep the most important responsibility of our form within one, pre-defined method. `persist` (being called by `save`) sounds to be a good name for it, but anything expressive and self-explanatory would work as well.



### Summary

As stated before, Form Object can help in mitigating a handful of various problems when implementing Rails projects and therefore with little effort it can prove to be a useful pattern in our toolbox. If you feel you might need some simple abstraction around form object pattern, consider trying the [reform](https://github.com/trailblazer/reform) gem or an even thinner layer provided by the [rails-patterns](https://github.com/Selleo/pattern#form) gem.

Form Object is a very useful pattern in rails ecosystem as it can address variety of issues and antipatterns. In this article we will attempt to sort out in which situations Form Objects can prove useful and what conventions allow us to make most out of them.

Read our blog fueled by years of development experience

Business

Technology

Essential Ruby On Rails Patterns

Essential RubyOnRails Patterns — Part 1: Service Objects

Essential RubyOnRails Patterns — Part 2: Query Objects

Essential RubyOnRails Patterns — Part 3: Clients And Wrappers

Essential RubyOnRails Patterns — Part 4: Form Objects

Tell us about your project