View Source Carve (Carve v0.3.0)
Carve simplifies JSON API development in Phoenix by automatically formatting endpoint outputs with associated links. Define resource relationships with a simple DSL, and let Carve handle link inclusion and query-based filtering, reducing boilerplate and ensuring consistent, flexible API responses.
It provides functionality for:
- Rendering JSON endpoints with links automatically
- Creating index/show methods for views from a DSL
- Retrieving links between different data types
- Encoding and decoding IDs using HashIds
- Configuring the application
Summary
Functions
Configures Carve with the given arguments.
Decodes a hash without a type using HashIds.
Decodes a hash with a given type using HashIds.
Encodes an ID for a given type using HashIds.
Determines if the include parameter was specified in the query string.
Retrieves links for a given module and data or ID(s).
Parses the include parameter from the query string parameters.
Starts the Carve application.
Functions
Configures Carve with the given arguments.
This function is typically called during application start, but can also be used to reconfigure Carve at runtime.
Parameters
args: A keyword list of configuration options.
Examples
iex> Carve.configure(salt: "my_salt", min_length: 8)
:okDecodes a hash without a type using HashIds.
This function attempts to decode the hash without knowing its type.
Parameters
hash: The string hash to decode.
Returns
The decoded integer ID.
Examples
iex> Carve.decode("abc123def")
{:ok, 123}Decodes a hash with a given type using HashIds.
Parameters
type: The type of the ID (as an atom).hash: The string hash to decode.
Returns
The decoded integer ID.
Examples
iex> Carve.decode(:user, "abc123def")
{:ok, 123}Encodes an ID for a given type using HashIds.
Parameters
type: The type of the ID (as an atom).id: The integer ID to encode.
Returns
A string representing the encoded ID.
Examples
iex> Carve.encode(:user, 123)
"abc123def"Determines if the include parameter was specified in the query string.
Parameters
params: The full params map from the controller.
Returns
true: If the include parameter was specified (even if empty).false: If the include parameter was not specified at all.
Examples
iex> Carve.include_param_specified?(%{"include" => "foo,bar"})
true
iex> Carve.include_param_specified?(%{"include" => ""})
true
iex> Carve.include_param_specified?(%{})
falseRetrieves links for a given module and data or ID(s).
This function supports various input types:
- Single integer ID
- List of integer IDs
- Single map (data structure)
- List of maps (data structures)
Parameters
module: The module to retrieve links for.data_or_ids: The data or ID(s) to retrieve links for.
Returns
A list of link maps, each containing :type, :id, and :data keys.
Examples
iex> Carve.links(PostJSON, 1)
[%{type: :user, id: "abc123", data: %{...}}, %{type: :comment, id: "def456", data: %{...}}]
iex> Carve.links(PostJSON, [1, 2, 3])
[%{type: :user, id: "abc123", data: %{...}}, %{type: :comment, id: "def456", data: %{...}}, ...]
iex> Carve.links(PostJSON, %{id: 1, title: "Test Post"})
[%{type: :user, id: "abc123", data: %{...}}, %{type: :comment, id: "def456", data: %{...}}]Parses the include parameter from the query string parameters.
This function determines if the include parameter was specified and parses it accordingly.
Parameters
params: The full params map from the controller.
Returns
nil: If the parameter was not specified (include everything).[]: If an empty string was passed.[atom]: A list of atoms representing the types to include.
Examples
iex> Carve.parse_include(%{"include" => "foo,bar"})
[:foo, :bar]
iex> Carve.parse_include(%{"include" => ""})
[]
iex> Carve.parse_include(%{})
nilStarts the Carve application.
This function is called automatically by the OTP application behaviour.
It configures Carve using the configuration returned by Carve.Config.get/0.
Returns
{:ok, pid}: The pid is the process identifier of the started application.