JSON API nicer include syntax

[willcosgrove]

I have a lot of nested associations in my app, and was getting tired of writing really long strings/arrays for the include option. So I wrote a little helper that turns an include that looks like this:

render json: @project_group, include: [projects: [project_tasks: [:part, :specification_revisions, :technique, :estimated_by, :comments, task: [:area]]]]

into an include value that looks like that

render json: @project_group, include: ["projects", "projects.project_tasks", "projects.project_tasks.task", "projects.project_tasks.task.area", "projects.project_tasks.part", "projects.project_tasks.specification_revisions", "projects.project_tasks.technique", "projects.project_tasks.estimated_by", "projects.project_tasks.comments"]

I tried to follow the format of what you can pass in to ActiveRecord::Relation#includes method.

It's a little messy but something along these lines:

  def sanitize_includes(includes, nest: [])
    case includes
    when Array
      includes.flat_map { |include|
        case include
        when Hash
          include.map { |key, value|
            [
              (nest + [key]).join('.'),
              sanitize_includes(value, nest: nest.push(key)),
            ]
          }
        else
          (nest + [include]).join('.')
        end
      }.flatten
    else
      includes
    end
  end

Does this sound helpful to anyone else? I wouldn't mind submitting a PR if it sounds like people are interested.

[NullVoxPopuli]

I can work on this once my json adapter implementation is merged

[NullVoxPopuli]

See #1113 and #1127

[beauby]

I like the idea of a better syntax for include, especially since nested resources are by essence a tree structure. However, I think it would make more sense to actually transform the text syntax (the current one) into a tree (i.e. an array of hash/symbols), than the opposite. Will open a PR for JSONAPI.

[NullVoxPopuli]

But why use the string syntax? what does it get us?

[beauby]

@NullVoxPopuli I would like to get rid of the string syntax but

1. it might be a concern to people who already use it
2. for some simple cases (like no nesting), people might arguably prefer 'author, comments' to [ :author, :comments ]

[beauby]

Also, the string syntax makes it easy to sideload a "grand child" resource without sideloading the "child resource", which I don't really see a use case of, but still.

[NullVoxPopuli]

@beauby we could support both?, esp if the string is gonna get converted to the array/hash syntax anyway.
The include array/hash could be used to do grandchild stuff, but there would need to be a defined way to skip the child's full serialization. maybe adding a relationships_only: true or something similar?

like:

[
  :author, 
  comments: {
    relationships_only: true, 
    associations: [:author]
  }
]

but that is getting kinda verbose... :-(

[jfelchner]

I think you all need to stick to one or the other. Supporting both adds unneeded complexity for little benefit. I personally think that if strings are passed in, they should be converted over to a Hash. If a Hash is passed in, it is used as-is.

[beauby]

@jfelchner The idea is to support an "hybrid" syntax, which is made of Arrays of Symbols and Hashes of Arrays (in terms of grammar, it would be something along the lines of S → Array[Symbol, Hash[S]])), which is more user-friendly than a pure hash (that would be for instance { comments: { author: {} }, author: {}, posts: {} }, where the hybrid syntax would allow [ :author, :posts, comments: [:author]].

[jfelchner]

Also, whatever does the conversion from the strings to hashes internally needs to be able to be called as a utility method. This way if the user wants to pass in include as a query param, the user can transform it into a Hash and then use some sort of whitelisting to make sure that someone didn't pass in something nefarious.

For example if I have an association called super_secret_stuff which I use for my admins, I don't want a user to be able to include super_secret_stuff.

[jfelchner]

@beauby agreed 👍 That's what I meant by "Hash". I don't know why you didn't catch on. 😉 😄

[beauby]

@jfelchner That seems like an authorization concern I am not sure AMS should be responsible of. Currently you could get away with defining two serializers, one for the Admins, one for the Users, which define different sets of relationships, and only the relationships declared in the serializer can be included.

[beauby]

@jfelchner If we agree on the format of include, I think you will be pleased by #1131 (although it states that the string syntax is removed, I'm actually adding it back since I overlooked the JSONAPI spec on that one).

[jfelchner]

@beauby no no. It definitely shouldn't be responsible for authorization. What I'm saying is something like:

class MyController
  def index
    render json: @project_group,
           include: sanitized_includes
  end

  private

  def sanitized_includes
    hashified_params = ActiveModel::Serializer.convert_string_includes_to_hash(params[:includes])

    ActionController::Parameters.new(hashified_params).permit(:blah, :blah)
  end
end

Obviously just pseudocode. The general gist is that users of AMS won't have to duplicate the logic of how the foo.bar.baz include string gets converted to { foo: { bar: :baz } or whatever. And they can then take that and apply whatever authorization logic is appropriate for that request.