phoenix-json-api

Phoenix JSON API

RULES — Follow these with no exceptions

1. Use the :api pipeline — don't mix HTML and JSON pipelines; API routes skip CSRF, sessions, and browser headers
2. Render errors as structured JSON — {:error, changeset} must become {"errors": {...}}; never return raw text or HTML errors
3. Use offset/limit for pagination — never return unbounded collections; default to a sensible limit (e.g., 20)
4. Version APIs via URL prefix (/api/v1/) — not headers; URL versioning is visible, cacheable, and debuggable
5. Use FallbackController for consistent error handling — every action returns {:ok, result} or {:error, reason}; the fallback renders errors
6. Authenticate via Bearer tokens in Authorization header — not cookies; API clients don't have browser sessions
7. Use json/2 helper — ensures Content-Type: application/json; avoid render for simple JSON responses

---

API Pipeline Setup

# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  pipeline :api do
    plug :accepts, ["json"]
    # No :fetch_session, :protect_from_forgery, :put_secure_browser_headers
    # APIs use tokens, not sessions
  end

  pipeline :api_auth do
    plug MyAppWeb.Plugs.ApiAuth
  end

  # Public endpoints (no auth required)
  scope "/api/v1", MyAppWeb.API.V1, as: :api_v1 do
    pipe_through :api

    post "/auth/login", AuthController, :login
    post "/auth/register", AuthController, :register
  end

  # Protected endpoints
  scope "/api/v1", MyAppWeb.API.V1, as: :api_v1 do
    pipe_through [:api, :api_auth]

    resources "/posts", PostController, except: [:new, :edit]
    resources "/users", UserController, only: [:index, :show, :update]
  end
end

---

Controller Pattern

Controllers return {:ok, result} or {:error, reason} — the FallbackController handles error rendering.

defmodule MyAppWeb.API.V1.PostController do
  use MyAppWeb, :controller

  alias MyApp.Blog
  alias MyApp.Blog.Post

  action_fallback MyAppWeb.FallbackController

  def index(conn, params) do
    page =
      case Integer.parse(params["page"] || "1") do
        {n, ""} when n > 0 -> n
        _ -> 1
      end

    per_page = Map.get(params, "per_page", "20") |> String.to_integer() |> min(100)

    {posts, total} = Blog.list_posts(page: page, per_page: per_page)

    conn
    |> put_resp_header("x-total-count", to_string(total))
    |> json(%{
      data: Enum.map(posts, &post_json/1),
      meta: %{page: page, per_page: per_page, total: total}
    })
  end

  def show(conn, %{"id" => id}) do
    with {:ok, post} <- Blog.get_post(id) do
      json(conn, %{data: post_json(post)})
    end
  end

  def create(conn, %{"post" => post_params}) do
    with {:ok, %Post{} = post} <- Blog.create_post(post_params) do
      conn
      |> put_status(:created)
      |> put_resp_header("location", ~p"/api/v1/posts/#{post}")
      |> json(%{data: post_json(post)})
    end
  end

  def update(conn, %{"id" => id, "post" => post_params}) do
    with {:ok, post} <- Blog.get_post(id),
         {:ok, %Post{} = updated} <- Blog.update_post(post, post_params) do
      json(conn, %{data: post_json(updated)})
    end
  end

  def delete(conn, %{"id" => id}) do
    with {:ok, post} <- Blog.get_post(id),
         {:ok, _} <- Blog.delete_post(post) do
      send_resp(conn, :no_content, "")
    end
  end

  defp post_json(%Post{} = post) do
    %{
      id: post.id,
      title: post.title,
      body: post.body,
      inserted_at: post.inserted_at,
      updated_at: post.updated_at
    }
  end
end