# DSL: 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](#json_api-routes) * get * index * post * patch * delete * related * relationship * post_to_relationship * patch_relationship * delete_from_relationship * [primary_key](#json_api-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
includes	`any`	[]	A keyword list of all paths that are includable from this resource
include_nil_values?	`any`		Whether or not to include properties for values that are nil in the JSON output

## json_api.routes Configure the routes that will be exposed via the JSON:API ### Nested DSLs * [get](#json_api-routes-get) * [index](#json_api-routes-index) * [post](#json_api-routes-post) * [patch](#json_api-routes-patch) * [delete](#json_api-routes-delete) * [related](#json_api-routes-related) * [relationship](#json_api-routes-relationship) * [post_to_relationship](#json_api-routes-post_to_relationship) * [patch_relationship](#json_api-routes-patch_relationship) * [delete_from_relationship](#json_api-routes-delete_from_relationship) ### 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		The base route for the resource, e.g `"/users"`

## json_api.routes.get ```elixir get action ``` A GET route to retrieve a single record ### Examples ``` get :read ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.index ```elixir index action ``` A GET route to retrieve a list of records ### Examples ``` index :read ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.post ```elixir post action ``` A POST route to create a record ### Examples ``` post :create ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
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
relationship_arguments	list(atom | {:id, atom})	[]	Arguments to be used to edit relationships. See the [relationships guide](/documentation/topics/relationships.md) for more.
upsert?	boolean	false	Whether or not to use the `upsert?: true` option when calling `YourApi.create/2`.
upsert_identity	atom	false	Which identity to use for the upsert

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.patch ```elixir patch action ``` A PATCH route to update a record ### Examples ``` patch :update ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
relationship_arguments	`any`	[]	Arguments to be used to edit relationships. See the [relationships guide](/documentation/topics/relationships.md) 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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.delete ```elixir delete action ``` A DELETE route to destroy a record ### Examples ``` delete :destroy ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.related ```elixir related relationship, action ``` A GET route to read the related resources of a relationship ### Examples ``` related :comments, :read ``` ### Options

Name	Type	Default	Docs
relationship *	atom
action *	atom		The action to call when this route is hit
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.relationship ```elixir relationship relationship, action ``` A READ route to read the relationship, returns resource identifiers. ### Examples ``` relationship :comments, :read ``` ### Arguments

Name	Type	Default	Docs
relationship *	atom

### Options

Name	Type	Default	Docs
action *	atom		The action to call when this route is hit
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.post_to_relationship ```elixir post_to_relationship relationship ``` A POST route to create related entities using resource identifiers ### Examples ``` post_to_relationship :comments ``` ### Options

Name	Type	Default	Docs
relationship *	atom
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.patch_relationship ```elixir patch_relationship relationship ``` A PATCH route to update a relationship using resource identifiers ### Examples ``` patch_relationship :comments ``` ### Options

Name	Type	Default	Docs
relationship *	atom
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

### Introspection Target: `AshJsonApi.Resource.Route` ## json_api.routes.delete_from_relationship ```elixir delete_from_relationship relationship ``` A DELETE route to remove related entities using resource identifiers ### Examples ``` delete_from_relationship :comments ``` ### Options

Name	Type	Default	Docs
relationship *	atom
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

### 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 *	`any`		the list of attributes to encode JSON API primary key
delimiter	String.t	"-"	The delimiter to concatenate the primary key values. Default to be '-'