Jsonapi-resources: Documentation Suggestion: refer to JSONAPI:Utils

[eccegordo]

This is more of a suggestion for documentation.

The guides should perhaps make a prominent reference to

https://github.com/tiagopog/jsonapi-utils

It would be helpful to have a a shout out to this project and maybe a brief compare and contrast so that people naively coming to JR understand there is also the Utils thing built on top of JR if they need the extra flexibility in their controller actions.

I know I would have had a lot less head scratching. I have been looking at JR off and on for a couple years but just now realizing Utils exists and probably makes more sense for my specific needs.

[scottgonzalez]

Would you mind providing some examples of what caused the head scratching? Based on the examples in their README, I think you'd end up with less code just using JR directly and creating an ApplicationResource class that just exposes every attribute from the model for its subclasses.

[scottgonzalez]

Actually, having now read the full example section, it looks like using JU will always result in writing more code. It seems to me like JU just makes you rewrite the controller logic that ships with JR.

[eccegordo]

Hi Scott,

I think what is confusing for me is just how you are suppose to override the behavior in controllers. I can appreciate that JR is probably less boilerplate than JU. But would like to better understand how you can customize the controller actions. Maybe I just don’t grok the Operation Prossessor and or callbacks. Or just need to see better concrete examples of overriding conventional with custom behaviors in the controller.

A couple specific examples:

1.) How to make an index action customizable. In my application I have a lot of scenarios where I actually don’t want the index action to just return a SomeModel.all result.

2.) I want to customize the way a particular model find_by works where I am not necessarily looking up a record by the id column but some other column in the table.

example.com/thing/abc-123

(:id) segment is not necessarily referring to the auto incrementing id column but I have a custom find method either in my model or else a custom show action in my controller that finds the single record in a way that might not be perfectly conventional ActiveRecord.

My challenge is I have a rails 4 API that I am using with ember that was developed before JSONAPI hit 1.0 spec. So it has a lot of complicated model implementations and bespoke serializer behavior that is 80% JSONAPI but not completely spec. And I am trying to migrate this thing over to Rails 5.2 and also hoping to use JR to make my JSON more compliant with the JSONAPI spec, and modern Ember Data.

[scottgonzalez]

But would like to better understand how you can customize the controller actions. Maybe I just don’t grok the Operation Prossessor and or callbacks. Or just need to see better concrete examples of overriding conventional with custom behaviors in the controller.

For the most part, you shouldn't be overriding logic in the controller actions. The questions you're asking seem to be specific to finders. However, I think there is definitely value is providing a few simple examples that are not tied into the massive guide of how to use every aspect of JR. I would guess that the examples listed in the JU README would be a good starting point.

1.) How to make an index action customizable. In my application I have a lot of scenarios where I actually don’t want the index action to just return a SomeModel.all result.

This scenario is very simple to handle with the self.records method. Simply return an ActiveRecord::Relation with the relevant models. Any data that's available in the controller can be provided to the resource via context.

2.) I want to customize the way a particular model find_by works where I am not necessarily looking up a record by the id column but some other column in the table.

The id column on the model doesn't really matter here, but this look up must be done by the id used in the resource. Each model or resource can define which attribute to use for the primary key. You already need to handle this in JU anyway in order to return a properly serialized response (and once again this is less code if you use JR directly).

My challenge is I have a rails 4 API that I am using with ember that was developed before JSONAPI hit 1.0 spec. So it has a lot of complicated model implementations and bespoke serializer behavior that is 80% JSONAPI but not completely spec. And I am trying to migrate this thing over to Rails 5.2 and also hoping to use JR to make my JSON more compliant with the JSONAPI spec, and modern Ember Data.

JR is definitely going to do everything it can to force you into having a spec-compliant response. With that being said, if your goal is to be 100% compliant, JU is basically a foot gun. It makes it much easier to make a mistake and not notice.

---

I'd also like to circle back to your first comment:

It would be helpful to have a a shout out to this project and maybe a brief compare and contrast so that people naively coming to JR understand there is also the Utils thing built on top of JR if they need the extra flexibility in their controller actions.

This is actually a topic that I care about a lot, and I've advocated for these comparisons for a long time. I've even given a talk about the problems that developers face when having to choose between modules. If we do nothing else, I think we should address this one issue.

[eccegordo]

Thanks for the tips.

Yeah I whole heartedly agree about the comparison stuff. Sometimes just a little explanation of why a particular library exists can go a long way.

With JSONAPI and rails in particular it is a confusing array or solutions. (JR, JU, AMS, fast_jsonapi, etc). And then to understand the serializer vs the more opinionated solution like JR.

I know for me personally I learn best by seeing concrete examples. The peeps app probably needs just another model or two to flesh out the full range of possibilities that JR enables.

If you know of any other "semi complicated" examples of JR based projects on GitHub please point to them. I would be curious.

[eccegordo]

Sweet! I figured out one of my basic issues.

I needed to do

key_type :string 

In one of my resources.

I think a more illustrative example app with some slightly non conventional examples would make this more clear. But rereading the guides cleared this up now that I understand the issue.

I am sure I will have more questions with side loading and and more complex uses of AREL and custom SQL queries. Basically how to use JR when things are not perfectly conventional ActiveRecord.