Support for views and scopes

[CiTroNaK]

First, I would like to thank you for this gem.

One thing I like about the Blueprinter gem is the view feature. I know a feature request of this kind (please can we have X from Y) is not the most popular, so before I jump on creating PR, I would like to know if that would be accepted (if it makes sense for Alba).

Why Alba and not Blueprinter?

We are looking for a more performant serializer that is also well-maintained (Blueprinter was forked, but the future is uncertain).

Alba shares some concepts from Blueprinter, and thus it will be easier for us to use it.

The problem

Let me start with a use case where we leverage it a lot: API versioning.

We did a lot of refactoring (to remove duplication mainly) on our backend Rails app. Part of it, we moved from v1, v2, etc., to monthly named API versions for our public API (it does not mean we have one release per month, but it helps with the depreciation strategy).

From many controllers that shared code between API versions (or inherited from each other) and many jbuilder files, we now have just one controller/action per endpoint, and the proper output (based on the API version) is processed in the serializer.

We set the requested API version using this scope in routes:

# config/routes.rb

scope "/:version", as: :public_api, module: :public_api, constraints: PublicApi::VersionConstraint.new do
  # resources ...
end

Example of the solution with views

Here is a small example of the solution that we are now using. Imagine we have 4 API versions: 2022-06, 2022-08, 2022-10, and 2022-12.

For 2022-10, we changed the names of two fields (a typical breaking change) from address_line_1 to line_1. This is how our serializer would look like:

module PublicApi
  class AddressBlueprint < BaseBlueprint
    view :v2022_06 do
      fields :id, :company_name, :contact_name, :contact_email, :contact_phone,
        :address_line_1, :address_line_2, :postal_code, :city, :state, :country_alpha2
    end

    view :v2022_10 do
      include_view :v2022_06
      excludes :address_line_1, :address_line_2 # removing fields inherited from the view

      field :address_line_1, name: :line_1 # renaming the field
      field :address_line_2, name: :line_2  # renaming the field
    end
  end
end

How it would be used for each API version:

• 2022-06 defines the fields and uses them all
• 2022-08 has no changes in this serializer, so the previous version is used (2022-06).
• 2022-10 has changes, so it includes the previous version (include_view) and does the renaming (excludes the two fields and adds them under a new name).
• 2022-12 has no changes in this serializer, so the previous version is used (2022-10).

We also have support for the classical usage of views. Here is a small example:

module PublicApi
  class ItemCategoryBlueprint < BaseBlueprint
    view :v2022_06 do
      include_view :v2023_01_basic

      fields :slug
    end

    view :v2022_06_basic do
      fields :id, :name
    end
  end
end

# usage
PublicApi::ItemCategoryBlueprint.render(item_category, view: :basic) # for `v2022_06_basic`
PublicApi::ItemCategoryBlueprint.render(item_category) # for `v2022_06`

Our usage

For this work, we only added a small piece of code that finds the correct view based on the requested API version (and the defined view on render/or in a blueprint association) on the serializer.

This works for our use case. We know it is only a temporary solution we are evaluating (another way is using a class-based solution, not a view based).

We also know that if we want to keep it, we need to improve it (see below for scopes). We also have a deprecation strategy for API versions and do not expect a long list of versions in each serializer, where it could become unusable/hard to maintain.

Main benefits:

• Releasing a new API version means adding a new version view to serializers that have breaking changes and allowing the new version in PublicApi::VersionConstraint.
• Newly added fields will be propagated to newer versions (when added in 2022-06, they will be available to all newer versions).

A small upgrade to the solution

Another concept that would be useful for our usage: scopes.

Here is something (based on the Blueprinter DSL) that I would like to see as a final "version":

module PublicApi
  class ItemCategoryBlueprint < BaseBlueprint
    scope :v2022_06 do
      view :basic do
        fields :id, :name
      end

      view :extended do
        include_view :basic

        fields :slug
      end
    end

    scope :v2022_10 do
      view :basic do
        include_view :basic, scope: :v2022_06

        # ... changes
      end
    end
  end
end

What do you think about it? Does it make sense for Alba to support something like that?

Thank you.

[okuramasafumi]

@CiTroNaK Hi, thank you for the suggestion.
So what I understand now is that you want to have two similar but different serializers like below:

class FooResourceV1 < BaseResource
  attributes :a, :b, :c
end

class FooResourceV2 < BaseResource
  attributes :a, :b, :c, :d
end

One of the solutions currently available is to use inheritance.

class BaseFooResource < BaseResource
  attributes :a, :b, :c
end

class FooResourceV1 < BaseFooResource
end

class FooResourceV2 < BaseFooResource
  attributes :d
end

The problem of this approach is that it's not flexible due to the nature of inheritance.

So, what I'm considering to add to Alba is something like below:

Alba.register :base_foo_attributes do
  attributes :a, :b, :c
end

class FooResourceV1 < BaseResource
  base_foo_attributes
end

class FooResourceV2 < BaseResource
  base_foo_attributes
  attributes :d
end

This approach lets us compose multiple "pre-registered" sets of attributes. I believe this is as flexible as the view of Blueprinter.

I'm going to implement it if you think it's good enough.

[CiTroNaK]

Hi @okuramasafumi, thank you for the response.

Yes, the class inheritance is not the best for our use case. That's why we first tried the view functionality of Blueprinter (and it works).

The main idea I tried to express in my first post is to have one serializer for each resource that can be used with many API versions (thanks to scopes) and different needs in different places (views; e.g., we don't need all associations on index responses, but we want all of them for show, or when the serializer is used in association, we need only specific fields).

In that way:

• We don't need to touch the controller, where the serializer is called (the same as for our service objects that are called in the controller) = one controller can serve all API versions (no duplicity in our codebase).
• It is easier to follow and see what each API version will have, as all are in one file.
• It is easier to use - just one class that is responsible for it and the correct output is set by the requested API version (the logic here is not described).

Using views, we can cover more use cases of the serializer - sometimes, we need only a smaller number of fields, or we don't need all associations. One class for each could make it harder to maintain and work with.

Using the scopes for API versions would help us to structure the DSL better.

If you need more information, please, don't hesitate to ask. I can also provide more examples to make it more explicit.

I will happily create PRs with support for views and later scopes if you find them worthy of Alba 🙂

Using the Alba.register, would not work for our use case as it would require one class per view and scope (based on the proper naming).

[okuramasafumi]

If you want to use only one serializer for different versions of API, you might be able to utilize params.

class FooResource < BaseResource
  attributes :a, :b, :c
  attributes :d, if: proc { params[:version] == '2023_02' }
end

This is not a complete alternative to views, but does similar things.

The code like below might be better for versioning use case though it's not implemented yet:

class FooResource < BaseResource
  attributes :a, :b, :c
  conditional proc { params[:version] == '2023_02' } do
    attributes :d
  end
end