[RFC] Automatic serializer lookup

[beauby]

TL;DR

What should be the lookup mechanism when inferring a serializer for a resource?

Proposal

What seems to make most sense is the following:

# resource.class == ::ResNamespace::Resource
# controller.class == ::Api::V1::ResourcesController
lookup_chain = prefixes(controller.class.to_s).map { |p| "#{p}::#{resource.class}Serializer" }
# => [ "::Api::V1::ResourcesController::ResNamespace::ResourceSerializer", 
# "::Api::V1::ResNamespace::ResourceSerializer",
# "::Api::ResNamespace::ResourceSerializer",
# "::ResNamespace::ResourceSerializer" ]

# When the resource is serialized as an association of an other serializer, say SerNamespace::OtherResourceSerializer,
# add "SerNamespace::OtherResourceSerializer::ResNamespace::ResourceSerializer" at the beginning of the lookup chain 

Implemented in #1436.

Current situation

Work has been done to get us to a more flexible situation in this regard.

The whole automatic lookup can be disabled by setting ActiveModelSerializers.config.automatic_lookup = false from within an initializer.

Currently, for a resource CoolNamespace::CoolResource, AMS will look for a CoolResourceSerializer in the following namespaces:

• If it is being serialized as an association of some other resource using OtherNamespace::OtherResourceSerializer, first look for OtherNamespace::OtherResourceSerializer::CoolResourceSerializer (this is designed so that defining single-purpose serializers for associations is less cumbersome),
• otherwise, look for CoolNamespace::CoolResourceSerializer (this is kind of the "normal" lookup),
• if none is found, recursively do the same for the superclass of CoolResource.

Other possible places we might want to look at:

• the calling controller's namespace (Controller namespace lookup. #1436), i.e. when doing render json: @posts inside Api::V1::PostsController#index, look for Api::V1::PostSerializer,
• the calling controller's namespace, concatenated with the resource's namespace, i.e. when doing render json: @cool_resources inside Api::V1::CoolResourcesController#index, look for Api::V1::CoolNamespace::CoolResourceSerializer (@natematykiewicz),
• all of the calling controller's prefix namespaces (in the previous case it would be ::Api::V1, ::Api, and ::,
• the parent serializer's namespace, i.e. when serializing CoolResource as an association through OtherNamespace::OtherResourceSerializer, look for OtherNamespace::CoolResourceSerializer (so that when you do render @post, serializer: Experimental::CoolFeature::PostSerializer, the post's author can be inferred to be Experimental::CoolFeature::AuthorSerializer),
• a user-specified list of namespaces,
• possibly many other things.

Possible API for user-provided paths

• add callbacks at the beginning and end of the lookup chain

Please chip in with your ideas, use-cases and strong opinions!

[beauby]

(cc @bf4, @joaomdmoura)

[bf4]

Change to pr?

[bf4]

Mention this is controller can be disabled by a global option or by supplying adapter:nil to the render call.

[bf4]

Mention 0.9 behavior w serializer_nanespace option to limit the cases ams had to handle. Could ve an option to serialization context

[natematykiewicz]

I believe this is related to my ticket: #1337

I've had a use-case where I had CoolNamespace::CoolResource and the serializer I needed to use was Api::V1::CoolNamespace::CoolResourceSerializer because the request came from Api::V1::CoolNamespaceController. Furthermore, I wanted my resource to have a root_node of cool_resource instead of cool_namespace/cool_resource. I don't expect this to become default behavior, but it is something I've actually done.

In my case, CoolNamespace was actually the name of a third-party vendor I was interfacing with, and CoolResource was the name of one of the few resources I needed to get from/create with them. This app has a few functions, one of which being an API for dealing with third-party vendors, so that when they randomly decide to change their spec on us, we can change it in one place company-wide instead of many apps that need to talk to these vendors.

[beauby]

@natematykiewicz It is indeed (and I haven't forgotted #1337, but thought I'd make an issue to broaden the scope a bit).
I agree that Api::V1::CoolNamespace::CoolResourceSerializer would make sense as well in many situations.

[beauby]

I just edited the issue to add your suggestion. If this RFC gets a bit of traction, I'll turn it into a PR so that everyone can chip in easily.

[natematykiewicz]

@beauby my app actually isn't Api::V1::CoolResourceController#index but instead Api::V1::CoolNamespaceController#cool_resource. We chose to make a controller per vendor. Though, I could see being more RESTful and making a Api::V1::CoolNamespace::CoolResourceController instead. The thing is, these vendors are not RESTful, and don't have many actions to them, so making a single controller for each vendor felt like it made more sense than trying to break their actions into resources, which felt like overkill. But, that's why I felt like I didn't necessarily expect this to be any sort of default behavior.

Thanks for acknowledging #1337!

[beauby]

@natematykiewicz I see. Note that in the scenario I described, it does not make a difference what your controller/action is called, since only its namespace is used.

[natematykiewicz]

Oh, right. 👍🏻

[bdmac]

I think the line mentioning "all of the calling controller's prefix namespaces" addresses my use-case in #1338. Just to bring that inline here:

#1338 adds support for modifying the lookup chain for a serializer's relationships based on its own namespace. Concretely, given:

class Public::V1::PostSerializer
  belongs_to :author
end

class Public::V1::AuthorSerializer
end

we will wind up with the following items in the lookup chain for an
author when serializing a Post with Public::V1::PostSerializer:

['Public::V1::PostSerializer::AuthorSerializer',
'Public::V1::AuthorSerializer', 'Public::AuthorSerializer',
'::AuthorSerializer']

This preserves the functionality of the single-purpose serializers by leaving them highest in the chain but allows for sibling serializers that are not nested below the active serializer to also be utilized.

[natematykiewicz]

@bdmac++ Sibling lookup is actually something I would love to see as well (#1337), though your PR seems to cover even more cases that I hadn't thought of.