View Source Carve (Carve v0.1.1)
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.
Retrieves links for a given module and data or ID(s).
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)
:ok
Decodes 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"
Retrieves 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: %{...}}]
Starts 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.