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

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 "/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 (String.t/0) - Required. The resource identifier type of this resource in JSON:API

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

routes

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 "/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 (String.t/0) - Required. The base route for the resource, e.g "/users"

get

A GET route to retrieve a single record

Examples:

get :read

• :route (String.t/0) - The path of the route The default value is "/:id".

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

index :read

• :paginate? (boolean/0) - The default value is true.

• :route (String.t/0) - The path of the route The default value is "/".

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

post :create

• :route (String.t/0) - The path of the route The default value is "/".

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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_arguments (term/0) - 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 :update do
        argument :authors, {:array, :map}, allow_nil?: false  
        change manage_relationship(:authors, type: :append_and_remove) # 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 [].

• :upsert? (boolean/0) - Whether or not to use the upsert?: true option when calling YourApi.create/2. The default value is false.

• :upsert_identity (atom/0) - Which identity to use for the upsert The default value is false.

patch

A PATCH route to update a record

Examples:

patch :update

• :relationship_arguments (term/0) - 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 :update do
        argument :authors, {:array, :map}, allow_nil?: false  
        change manage_relationship(:authors, type: :append_and_remove) # 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 [].

• :read_action (atom/0) - The read action to use to look the record up before updating The default value is nil.

• :route (String.t/0) - The path of the route The default value is "/:id".

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

delete :destroy

• :read_action (atom/0) - The read action to use to look the record up before updating The default value is nil.

• :route (String.t/0) - The path of the route The default value is "/:id".

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

related :comments, :read

• :relationship (atom/0) - Required.

• :route (String.t/0) - The path of the route - Defaults to /:id/[relationship_name]

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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.

Examples:

relationship :comments, :read

• :relationship (atom/0) - Required.

• :route (String.t/0) - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :action (atom/0) - Required. The action to call when this route is hit

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

post_to_relationship :comments

• :relationship (atom/0) - Required.

• :route (String.t/0) - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

patch_relationship :comments

• :relationship (atom/0) - Required.

• :route (String.t/0) - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

Examples:

delete_from_relationship :comments

• :relationship (atom/0) - Required.

• :route (String.t/0) - The path of the route - Defaults to /:id/relationships/[relationship_name]

• :default_fields (list of atom/0) - A list of fields to be shown in the attributes of the called route

• :primary? (boolean/0) - 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

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 (String.t/0) - The delimiter to concatenate the primary key values. Default to be '-' The default value is "-".