View Source 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
- get
- index
- post
- patch
- delete
- related
- relationship
- post_to_relationship
- patch_relationship
- delete_from_relationship
- 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
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
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
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
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
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
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
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
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
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
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
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 '-' |