AshJsonApi.Resource

The entrypoint for adding JSON:API behavior to a resource"

json_api

Configure the resource's behavior in the JSON:API

Nested DSLs

routes
- get
- index
- post
- patch
- delete
- related
- relationship
- post_to_relationship
- patch_relationship
- delete_from_relationship
- route
primary_key

Examples

json_api do
  type "post"
  includes [
    friends: [
      :comments
    ],
    comments: []
  ]

  routes do
    base "/posts"

    get :read
    get :me, route: "/me"
    index :read
    post :confirm_name, route: "/confirm_name"
    patch :update
    related :comments, :read
    relationship :comments, :read
    post_to_relationship :comments
    patch_relationship :comments
    delete_from_relationship :comments
  end
end

Options

Name	Type	Default	Docs
`type`	`String.t`		The resource identifier type of this resource in JSON:API
`always_include_linkage`	`list(atom)`	`[]`	A list of relationships that should always have their linkage included in the resource
`includes`	`any \| list(any)`	`[]`	A keyword list of all paths that are includable from this resource
`paginated_includes`	`list(atom \| list(atom))`	`[]`	A list of relationship paths that can be paginated when included via the `included_page` query parameter. Each entry can be either an atom (for top-level relationships) or a list of atoms (for nested paths).
`include_nil_values?`	`any`		Whether or not to include properties for values that are nil in the JSON output
`default_fields`	`list(atom)`		The fields to include in the object if the `fields` query parameter does not specify. Defaults to all public
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource

json_api.routes

Configure the routes that will be exposed via the JSON:API

Examples

routes do
  base "/posts"

  get :read
  get :me, route: "/me"
  index :read
  post :confirm_name, route: "/confirm_name"
  patch :update
  related :comments, :read
  relationship :comments, :read
  post_to_relationship :comments
  patch_relationship :comments
  delete_from_relationship :comments
end

Options

Name	Type	Default	Docs
`base`	`String.t`		A base route for the resource, e.g `"/users"`

json_api.routes.get

get action

A GET route to retrieve a single record

Examples

get :read

get :read, path_param_is_composite_key: :id

Arguments

Name	Type	Default	Docs
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`route`	`String.t`	`"/:id"`	The path of the route
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.index

index action

A GET route to retrieve a list of records

Examples

index :read

Arguments

Name	Type	Default	Docs
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`paginate?`	`boolean`	`true`
`route`	`String.t`	`"/"`	The path of the route
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.post

post action

A POST route to create a record

Examples

post :create

Arguments

Name	Type	Default	Docs
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`route`	`String.t`	`"/"`	The path of the route
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.
`relationship_arguments`	`list(atom \| {:id, atom})`	`[]`	Arguments to be used to edit relationships. See the relationships guide for more.
`upsert?`	`boolean`	`false`	Whether or not to use the `upsert?: true` option when calling `Ash.create/2`.
`upsert_identity`	`atom`	`false`	Which identity to use for the upsert

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.patch

patch action

A PATCH route to update a record

Examples

patch :update

patch :update, path_param_is_composite_key: :id

Arguments

Name	Type	Default	Docs
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`relationship_arguments`	`any`	`[]`	Arguments to be used to edit relationships. See the relationships guide for more.
`read_action`	`atom`		The read action to use to look the record up before updating
`route`	`String.t`	`"/:id"`	The path of the route
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.delete

delete action

A DELETE route to destroy a record

Examples

delete :destroy

delete :destroy, path_param_is_composite_key: :id

Arguments

Name	Type	Default	Docs
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`read_action`	`atom`		The read action to use to look the record up before updating
`route`	`String.t`	`"/:id"`	The path of the route
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

related relationship, action

A GET route to read the related resources of a relationship

Examples

related :comments, :read

Arguments

Name	Type	Default	Docs
`relationship`	`atom`
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`route`	`String.t`		The path of the route - Defaults to /:id/[relationship_name]
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.relationship

relationship relationship, action

A READ route to read the relationship, returns resource identifiers.

Examples

relationship :comments, :read

Arguments

Name	Type	Default	Docs
`relationship`	`atom`
`action`	`atom`		The action to call when this route is hit

Options

Name	Type	Default	Docs
`route`	`String.t`		The path of the route - Defaults to /:id/relationships/[relationship_name]
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.post_to_relationship

post_to_relationship relationship

A POST route to create related entities using resource identifiers

Examples

post_to_relationship :comments

Arguments

Name	Type	Default	Docs
`relationship`	`atom`

Options

Name	Type	Default	Docs
`route`	`String.t`		The path of the route - Defaults to /:id/relationships/[relationship_name]
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.patch_relationship

patch_relationship relationship

A PATCH route to update a relationship using resource identifiers

Examples

patch_relationship :comments

Arguments

Name	Type	Default	Docs
`relationship`	`atom`

Options

Name	Type	Default	Docs
`route`	`String.t`		The path of the route - Defaults to /:id/relationships/[relationship_name]
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.delete_from_relationship

delete_from_relationship relationship

A DELETE route to remove related entities using resource identifiers

Examples

delete_from_relationship :comments

Arguments

Name	Type	Default	Docs
`relationship`	`atom`

Options

Name	Type	Default	Docs
`route`	`String.t`		The path of the route - Defaults to /:id/relationships/[relationship_name]
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.route

route method, route, action

A route for a generic action.

Examples

route :get, "say_hi/:name", :say_hello

Arguments

Name	Type	Docs
`method`	`atom`	The HTTP method for the route, e.g `:get`, or `:post`
`route`	`String.t`	The path of the route
`action`	`atom`	The action to call when this route is hit

Options

Name	Type	Default	Docs
`wrap_in_result?`	`boolean`	`false`	Whether or not the action result should be wrapped in `{result: <result>}`
`default_fields`	`list(atom)`		A list of fields to be shown in the attributes of the called route
`primary?`	`boolean`	`false`	Whether or not this is the route that should be linked to by default when rendering links to this type of route
`metadata`	`(any, any, any -> any)`		A function to generate arbitrary top-level metadata for the JSON:API response
`modify_conn`	`(any, any, any, any -> any)`		A function to modify the conn before responding. Used for things like setting headers based on the response. Takes `conn, subject, result, request`. See the modify_conn guide for more details and examples.
`query_params`	`list(atom)`	`[]`	A list of action inputs to accept as query parameters.
`action_names_in_schema`	`keyword`		A mapping of action names to how they should appear in the OpenAPI schema. You only need to set this if you see a warning during schema generation.
`name`	`String.t`		A globally unique name for this route, to be used when generating docs and open api specifications
`description`	`String.t`		A human-friendly description of this specific route to use in generated documentation and OpenAPI. If provided, this overrides the action description.
`derive_sort?`	`boolean`	`true`	Whether or not to derive a sort parameter based on the sortable fields of the resource
`derive_filter?`	`boolean`	`true`	Whether or not to derive a filter parameter based on the sortable fields of the resource
`path_param_is_composite_key`	`atom`		The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details.

Introspection

Target: AshJsonApi.Resource.Route

json_api.primary_key

Encode the id of the JSON API response from selected attributes of a resource

Examples

primary_key do
  keys [:first_name, :last_name]
  delimiter "~"
end

Options

Name	Type	Default	Docs
`keys`	`atom \| list(atom)`		the list of attributes to encode JSON API primary key
`delimiter`	`String.t`	`"-"`	The delimiter to concatenate the primary key values. Default to be '-'

← Previous Page Paginated Relationships

Next Page → AshJsonApi.Domain

AshJsonApi.Resource

json_api

Nested DSLs

Examples

Options

json_api.routes

Nested DSLs

Examples

Options

json_api.routes.get

Examples

Arguments

Options

Introspection

json_api.routes.index

Examples

Arguments

Options

Introspection

json_api.routes.post

Examples

Arguments

Options

Introspection

json_api.routes.patch

Examples

Arguments

Options

Introspection

json_api.routes.delete

Examples

Arguments

Options

Introspection

json_api.routes.related

Examples

Arguments

Options

Introspection

json_api.routes.relationship

Examples

Arguments

Options

Introspection

json_api.routes.post_to_relationship

Examples

Arguments

Options

Introspection

json_api.routes.patch_relationship

Examples

Arguments

Options

Introspection

json_api.routes.delete_from_relationship

Examples

Arguments

Options

Introspection

json_api.routes.route

Examples

Arguments

Options

Introspection

json_api.primary_key

Examples

Options