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

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 '-'