Humaans.Resource (Humaans v0.5.1)

Copy Markdown View Source

Macro for generating standard CRUD operations for Humaans API resources.

Resource modules can use Humaans.Resource to automatically generate list/2, create/2, retrieve/2, update/3, and delete/2 functions, reducing boilerplate while keeping each resource's behaviour explicit.

Options

  • :path (required) - The API path prefix, e.g. "/people"
  • :struct (required) - The resource struct module, e.g. Humaans.Resources.Person
  • :actions (optional) - List of actions to generate. Defaults to all five: [:list, :create, :retrieve, :update, :delete]
  • :doc_params (optional) - Keyword list of example param maps for create and/or update, as strings. Used to generate meaningful ## Examples in the docs. e.g. [create: "%{person_id: "abc", bank_name: "Barclays"}"]

Examples

defmodule Humaans.People do
  use Humaans.Resource,
    path: "/people",
    struct: Humaans.Resources.Person

  # All CRUD functions are generated automatically.
  # Override any function below if non-standard behaviour is needed.
end

defmodule Humaans.Companies do
  use Humaans.Resource,
    path: "/companies",
    struct: Humaans.Resources.Company,
    actions: [:list, :update]

  # Companies don't support create or delete via the API.
  # Retrieve is exposed as get/2 instead of the standard retrieve/2.
end

All generated functions are defoverridable, so resource modules can override individual operations without losing the generated ones.