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

• :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 :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

• :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 :read

• :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 :read

• :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 :create

• :relationship_arguments - A list of arguments that can be edited in the data.relationships input.
  
  This is primarily useful for those who want to keep their relationship changes in compliance with the JSON:API spec. If you are not focused on building a fully compliant JSON:API, it is likely far simpler to simply accept arguments in the attributes key and ignore the data.relationships input.
  
  If the argument's type is {:array, _}, a list of data will be expected. Otherwise, it will expect a single item.
  
  For example:

  # On a tweets resource  
  # With a patch route that references the `authors` argument
  json_api do
  routes do
  patch :update, relationship_arguments: [:authors]
  end
  end  
  # And an argument by that name in the action
  actions do
  update :cupdate do
  argument :authors, {:array, :map}, allow_nil?: false  
  change manage_relationship(:authors, type: :replace) # Use the authors argument to allow changing the related authors on update
  end
  end

  You can then send the value for authors in the relationships key, e.g

  {
  data: {
  attributes: {
    ...
  },
  relationships: {
    authors: {
      data: [
        {type: "author", id: 1}, // the `type` key is removed when the value is placed into the action, so this input would be `%{"id" => 1}` (`type` is required by `JSON:API` specification)
        {type: "author", id: 2, meta: {arbitrary: 1, keys: 2}}, <- `meta` is JSON:API spec freeform data, so this input would be `%{"id" => 2, "arbitrary" => 1, "keys" => 2}`
      ]
    }
  }
  }
  }

  If you do not include :authors in the relationship_arguments key, you would supply its value in attributes, e.g:

  {
  data: {
  attributes: {
    authors: {
      {id: 1},
      {id: 2, arbitrary: 1, keys: 2},
    }
  }
  }
  }

  Non-map argument types, e.g argument :author, :integer (expecting an author id) work with manage_relationship, but not with JSON:API, because it expects {"type": _type, "id" => id} for relationship values. To support non-map arguments in relationship_arguments, instead of :author, use {:id, :author}. This works for {:array, _} type arguments as well, so the value would be a list of ids. The default value is [].

• :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 :update

• :relationship_arguments - A list of arguments that can be edited in the data.relationships input.
  
  This is primarily useful for those who want to keep their relationship changes in compliance with the JSON:API spec. If you are not focused on building a fully compliant JSON:API, it is likely far simpler to simply accept arguments in the attributes key and ignore the data.relationships input.
  
  If the argument's type is {:array, _}, a list of data will be expected. Otherwise, it will expect a single item.
  
  For example:

  # On a tweets resource  
  # With a patch route that references the `authors` argument
  json_api do
  routes do
  patch :update, relationship_arguments: [:authors]
  end
  end  
  # And an argument by that name in the action
  actions do
  update :cupdate do
  argument :authors, {:array, :map}, allow_nil?: false  
  change manage_relationship(:authors, type: :replace) # Use the authors argument to allow changing the related authors on update
  end
  end

  You can then send the value for authors in the relationships key, e.g

  {
  data: {
  attributes: {
    ...
  },
  relationships: {
    authors: {
      data: [
        {type: "author", id: 1}, // the `type` key is removed when the value is placed into the action, so this input would be `%{"id" => 1}` (`type` is required by `JSON:API` specification)
        {type: "author", id: 2, meta: {arbitrary: 1, keys: 2}}, <- `meta` is JSON:API spec freeform data, so this input would be `%{"id" => 2, "arbitrary" => 1, "keys" => 2}`
      ]
    }
  }
  }
  }

  If you do not include :authors in the relationship_arguments key, you would supply its value in attributes, e.g:

  {
  data: {
  attributes: {
    authors: {
      {id: 1},
      {id: 2, arbitrary: 1, keys: 2},
    }
  }
  }
  }

  Non-map argument types, e.g argument :author, :integer (expecting an author id) work with manage_relationship, but not with JSON:API, because it expects {"type": _type, "id" => id} for relationship values. To support non-map arguments in relationship_arguments, instead of :author, use {:id, :author}. This works for {:array, _} type arguments as well, so the value would be a list of ids. The default value is [].

• :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 :destroy

• :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, :read

• :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, :read

• :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

• :relationship - Required.

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

• :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

• :relationship - Required.

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

• :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

• :relationship - Required.

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

• :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 "-".