phoenix-product-codex_cover_1200x1553464×600 49.2 KB

by Isaak Tsalicoglou

Why this book is being written

A few years ago I got fed up with the menial manual labor I was engaged in in our family business (TECTRA Ltd), in order to manage customer requests, product inventory, quotations and, most importantly for this book, the product catalog. Everything was paper-based, so one day I sat down and started developing a set of simple and powerful REST APIs with Python and FastAPI. These APIs have served us really well over the years (the full story is told on a Leanpub Frontmatter podcast episode, BTW). However, with the recent launch of the successor business (ISATEK, the website is made with Phoenix LiveView), I am re-implementing everything cleanly using Elixir and Phoenix.

This book is the “journal” of sorts of (re-)implementing a production-grade REST API for product data management, i.e. for managing data related to suppliers, product categories, product families, bundles and kits, and so on, with the ultimate goal of arriving at unique “sales items” and their data (prices, discounts, invoice descriptions, marketing content), as they are being offered and sold to clients.

Though this book contains some exploratory learning like Northwind Elixir Traders before it, it assumes basic familiarity with Elixir and Ecto, but zero knowledge of the “main course”, which is Phoenix, for building REST APIs in particular. So, as Northwind Elixir Traders primarily targets building Ecto skills, Phoenix Product Codex follows a similar exploratory-learning recipe for building Phoenix skills. Once again, we use SQLite, but there’s absolutely nothing stopping you from transferring what we build to PostgreSQL.

As with Northwind Elixir Traders, we do not follow a completionist approach: this book is not meant to cover every single nook and cranny of Phoenix. Instead, we set an ambitious goal and some sub-goals (e.g., interfacing with an external service for Tax ID validation, refreshing external data with a GenServer, implementing rate limiting, authentication and authorization, caching and invalidating database query results), and gradually accomplish all that by using everything at our disposal that makes sense–including any Hex.pm packages required, such as Viex and Mox. Sometimes, we have to backtrack; however the rationale behind every decision is covered, to convey once again not merely the “happy path”, but to provide a rich understanding of both the business domain and the technical approach to the goal(s).

What’s inside

The book was first published in a Work-In-Progress state on Leanpub on April 26th, 2025. It will continue to be updated approx. every second or third week (depending on my workload) until the full envisioned scope is realized. The chapters released so far cover:

• The business context and the goal
• Exploration of the database schema as it’s being shaped
• Domain-Driven Design and domain boundaries
• The conundrum of deciding on one taxonomy
• Modeling the first table (suppliers)
• Validating EU tax IDs with an external service (EU VIES)
• Implementing a validation plug with a helpful message, for mis-shaped JSON request bodies
• Implementing tests of the /api/suppliers endpoint with ExUnit
• Mocking the external service with Mox

Here is a non-exhaustive, prospective and tentative list of the topics that will be covered in chapters coming soon, some of which are already in development:

• Implementing the entire database step by step in Ecto
• Endpoints for all resources
• Application logic for issuing unique item codes
• Application logic for kitting/bundling
• Issuing bearer tokens, each with a different authorization for access to item fields
• Caching with Cachex
• A taxonomy with tags
• Pagination, filtering, and sorting
• Search across manufacturer codes and item descriptions
• Discontinued and replaced items
• “Related items” feature
• API rate limiting
• API versioning
• Webhooks for event notifications
• Bulk operations (import from CSV, export to CSV and XLS, possibly even to ODS)
• API documentation with Swagger/OpenAPI
• Multilingual descriptions
• Audit logging (tracking changes to prices)
• Production deployment and monitoring
• Database schema extensions for content management (tentative)

About the book

Dive into the real-world journey of building a production-ready Product Data Management REST API with Phoenix Product Codex. This isn’t just another Elixir or Phoenix tutorial, but a practical, hands-on tale of solving a critical business problem, straight from the trenches of a family-run industrial-equipment trading business. If you’ve ever wondered how to turn the “master data” of an expansive product portfolio into a structured, scalable system, this book is your guide.

In Phoenix Product Codex, you’ll follow the author’s path of implementing a REST API with Elixir and Phoenix on the basis of a pragmatically-implemented scrappy prototype that began years ago with government-mandated electronic invoicing, to a properly implemented self-hosted solution that has been serving as the Single Source of Truth of product data of two companies for five years.

Learn how to develop and deploy a robust and production-ready REST API using Elixir, Phoenix, Ecto, and SQLite, all while tackling real-world business conundrums, such as thinking about the database schema, organizing tables and modules in domains, considering how to codify a product catalog from scratch, issuing unique item codes with tricks that reduce the probability of typos wreaking havoc, using external APIs to validate data, keeping external data up-to-date with a GenServer, and ensuring data integrity even as the product portfolio grows in size and complexity. This book isn’t about a toy project or yet another to-do list, shopping cart, or Pokedex; it’s about shipping functional (in more ways than one) software that has kept a business running, day in and day out.

Much like Northwind Elixir Traders, what sets this book apart from other Phoenix tutorials is its blend of technical depth and business insights. You’ll not only master the nuts and bolts of building a REST API, such as domain modeling, database design and migrations, authentication and authorization, rate limiting, third-party API integrations, and GenServers, but you’ll also learn about the business-minded thinking behind every decision. Drawing from almost two decades years of experience split among corporate and entrepreneurial roles, the author shows you how to think like a business owner, a software engineer, and a problem-solver all at once. Whether you are an Elixir software engineer tasked with developing REST APIs for business processes, or the business analyst, product manager or general manager who oversees such project, this book is about helping you to wear both a technical and a business hat when considering what to build, and how to build it–and deploy it. This book will also prove useful if you are a small business owner who intends to digitize your business processes on your own terms.

Phoenix Product Codex is real-world focused, business-driven sequel to its technologies-focused and toy-database-based predecessor, Northwind Elixir Traders (which is still a great primer if you’re new to Elixir, Ecto or SQLite).

Grab a discounted copy during development

As with Northwind Elixir Traders, early adopters benefit from discounts.

For a limited time and number of copies, forum.elixirforum.com readers can get 20% off the minimum price with the following coupon link: Phoenix Product Codex [Leanpub PDF/iPad/Kindle]

Available as PDF and ePub on Leanpub:

Enjoy!