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

Table of Contents

• json_api
  • routes
    • get
    • index
    • post
    • patch
    • delete
    • related
    • relationship
    • post_to_relationship
    • patch_relationship
    • delete_from_relationship
  • primary_key

json_api

Configure the resource's behavior in the JSON:API

• 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_route "/posts"

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

• :type - Required. The resource identifier type of this resource in JSON:API

• :includes - A keyword list of all paths that are includable from this resource The default value is [].

routes

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

• get
• index
• post
• patch
• delete
• related
• relationship
• post_to_relationship
• patch_relationship
• delete_from_relationship

Examples:

routes do
  base_route "/posts"

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

• :base - Required. The base route for the resource, e.g "/users"

get

A GET route to retrieve a single record

Introspection Target:

AshJsonApi.Resource.Route

Examples:

get :default

• :route - The path of the route The default value is "/:id".

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

index

A GET route to retrieve a list of records

Introspection Target:

AshJsonApi.Resource.Route

Examples:

index :default

• :paginate? - The default value is true.

• :route - The path of the route The default value is "/".

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

post

A POST route to create a record

Introspection Target:

AshJsonApi.Resource.Route

Examples:

post :default

• :route - The path of the route The default value is "/".

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

patch

A PATCH route to update a record

Introspection Target:

AshJsonApi.Resource.Route

Examples:

patch :default

• :route - The path of the route The default value is "/:id".

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

delete

A DELETE route to destroy a record

Introspection Target:

AshJsonApi.Resource.Route

Examples:

delete :default

• :route - The path of the route The default value is "/:id".

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

related

A GET route to read the related resources of a relationship

Introspection Target:

AshJsonApi.Resource.Route

Examples:

related :comments, :default

• :relationship - Required.

• :route - The path of the route - Defaults to /:id/[relationship_name]

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

relationship

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

Introspection Target:

AshJsonApi.Resource.Route

Examples:

relationship :comments, :default

• :relationship - Required.

• :route - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

post_to_relationship

A POST route to create related entities using resource identifiers

Introspection Target:

AshJsonApi.Resource.Route

Examples:

post_to_relationship :comments, :default

• :relationship - Required.

• :route - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

patch_relationship

A PATCH route to update a relationship using resource identifiers

Introspection Target:

AshJsonApi.Resource.Route

Examples:

patch_relationship :comments, :default

• :relationship - Required.

• :route - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

delete_from_relationship

A DELETE route to remove related entities using resource identifiers

Introspection Target:

AshJsonApi.Resource.Route

Examples:

delete_from_relationship :comments, :default

• :relationship - Required.

• :route - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :action - Required. The action to call when this route is hit

• :primary? - Whether or not this is the route that should be linked to by default when rendering links to this type of route The default value is false.

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

• :keys - Required. the list of attributes to encode JSON API primary key

• :delimiter - false The delimiter to concatenate the primary key values. Default to be '-' The default value is "-".