AshJsonApi.Resource (ash_json_api v0.28.1) View Source

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

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

Link to this section Summary

Link to this section Functions