diff --git a/docs/general/adapters.md b/docs/general/adapters.md index dd86e9031..5d2a005d7 100644 --- a/docs/general/adapters.md +++ b/docs/general/adapters.md @@ -143,17 +143,22 @@ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema ### Include option -All built-in adapters allow to include the associated resources. Nested associated resources is also supported. -Use `include` option for this: +Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), but is available in all adapters. +Example of the usage: ```ruby render json: @posts, include: ['author', 'comments', 'comments.author'] # or render json: @posts, include: 'author,comments,comments.author' ``` -**Note:** Serializer classes must declare associations explicitly, using `belongs_to` and `has_many` and etc., for `include` option to work. -For JSON API adapter associated resources will be gathered in the `"included"` member. +The format of the `include` option can be either: + +- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes). +- an Array of Symbols and Hashes. +- a mix of both. + +An empty string or an empty array will prevent rendering of any associations. In addition, two types of wildcards may be used: @@ -166,11 +171,6 @@ These can be combined with other paths. render json: @posts, include: '**' # or '*' for a single layer ``` -The format of the `include` option can be either: - -- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes). -- an Array of Symbols and Hashes. -- a mix of both. The following would render posts and include: @@ -184,6 +184,20 @@ It could be combined, like above, with other paths in any combination desired. render json: @posts, include: 'author.comments.**' ``` +**Note:** Wildcards are AMS-specific, they are not part of the JSON API spec. + +The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations. + +For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes +adapters associated resources will be rendered among the other attributes. + +Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature +is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets): + +```ruby + render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] } +``` + ##### Security Considerations Since the included options may come from the query params (i.e. user-controller):