Improves documentation of belongs_to

[timrosenblatt]

Full credit to @brucec5 for discovering this functionality.

Purpose

#belongs_to docs were a little slim, and it took us a long time to realize that we could use this to essentially override the API's "foreign key".

I also bumped the docs slightly to make it clearer that this is a way you can send a different identifier out into the world for the JSON API relationships.

This is especially useful if you want to change the identifier you expose to the outside world instead of DB values. There are many reasons you might want to do this.

• https://softwareengineering.stackexchange.com/questions/346971/should-backend-ids-be-public-or-not-on-a-rest-api
• http://toddfredrich.com/ids-in-rest-api.html
• https://medium.com/lightrail/prevent-business-intelligence-leaks-by-using-uuids-instead-of-database-ids-on-urls-and-in-apis-17f15669fd2e

Changes

Pure docs. No code was harmed in the making of this pull request.

Caveats

This may not be the best way to change the identifier exposed to the outside world. I don't see any way that this usage would cause a problem, but I welcome feedback.

I'm a little surprised that AMS doesn't call Model#to_param to generate the identifier used in the relationships field.

[bf4]

@timrosenblatt @wasifhossain wanna bring this one home?

[wasifhossain]

@timrosenblatt thanks for bringing this up on the table. Would you mind fixing 2 rubocop issues (Metrics/LineLength: Line is too long) on L248/249 in lib/active_model/serializer.rb?

I am pasting the exact log of the offenses for your convenience

Offenses:
lib/active_model/serializer.rb:248:307: C: Metrics/LineLength: Line is too long. [383/251] (https://github.com/bbatsov/ruby-style-guide#80-character-limits)
    # @option options [Symbol] :foreign_key used by JSON:API on a `belongs_to` relationship to avoid unnecessarily loading the association object. This can also be used to override the `id` attribute set in the [`relationships` data field](http://jsonapi.org/format/#document-resource-object-relationships) if you are exposing a different value to the outside world instead of DB IDs
                                                                                                                                                                                                                                                                                                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
lib/active_model/serializer.rb:249:252: C: Metrics/LineLength: Line is too long. [298/251] (https://github.com/bbatsov/ruby-style-guide#80-character-limits)
    # @option options [Symbol] :namespace used when looking up the serializer and `serializer` is not given.  Falls back to the parent serializer's `:namespace` instance options, which, when present, comes from the render options. See [Rendering#namespace](rendering.md#namespace] for more details.

Once you do that, we can merge it happily :+1:

[wasifhossain]

@bf4 I found some recent PRs almost ready to be merged, but without final touch from the OPs, merging seems to be vulnerable to get delayed long enough.

Do you suggest me to take the move to copy the changes included in these PRs and credit the OPs in them somewhat like how PRs are merged in the Ruby repo?