Phoenix Product Codex

Develop and deploy a REST API for Product Data Management with Elixir and Phoenix

Transform chaos into order with Phoenix Product Codex: a thrilling, real-world journey of building a production-ready REST API for product data management using Elixir and Phoenix, born from the requirements of a family-run business facing a government mandate for electronic invoicing. Learn to craft and deploy a thoughtfully-designed, business-driven solution that already serves as the Single Source of Truth for two companies, while also mastering domain modeling, database design, and more in the process. No toy examples or databases here, but actual software that delivers real impact.

Latest version: v0.20.6, dated 2025-05-03

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 Isaak’s path of implementing a REST API in 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, Isaak 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 a decidedly shorter, yet more real-world focused and business-driven sequel to its technologies-focused and toy-database-based kinda-prequel, Northwind Elixir Traders (which is still a great primer if you’re new to Elixir, Ecto or SQLite).

Who is this book for?

This book has been written for anyone who already possesses some Elixir programming skill and and understanding of Ecto and wants to serve data from a database (SQLite, PostgreSQL, MySQL, really anything for which Ecto has a database adapter) from a REST API built with the Phoenix framework.

As with all my technical books, you’ll discover the joy of experimentation as we encounter unexpected hurdles and exercize our Elixir skills in figuring out why things don’t work as expected, and how to still get things done, regardless. Through these challenges, you’ll gain invaluable insights into how Phoenix works under the hood.

Embrace the ethos of fearless exploration as we delve deeper into the capabilities of Phoenix, focusing on the art of reading documentation and adapting to unforeseen obstacles. With each chapter, you’ll elevate your understanding of Phoenix and the business domain, empowering yourself to tackle similar real-world projects with confidence and finesse instead of with copy-paste operations and hopes and wishes that it all works out in the end.

For a curious Elixir newcomer exploring possibilities of building a REST API backend with Phoenix or a REST API served alongside a Phoenix LiveView app, Phoenix Product Codex promises an immersive learning experience that’s both enriching and unforgettable.

What kind of problems will you learn to solve?

On a high level, you will learn to solve problems such as:

Reasoning about the business domain, defining domain boundaries, and how to organize your codebase in a way that makes sense.
Developing various ways of slicing the complex cake of product data with different taxonomies.
Thinking through an Entity Relationship Diagram (ERD) and gradually transforming it into Elixir/Ecto code, and Phoenix endpoints corresponding to various resources and operations such as bulk import and export.
Thinking about real-world boundary conditions when developing a REST API like this one.
Testing your Elixir application, including API endpoints, with ExUnit.
Dealing with production-grade concerns, such as authentication, authorization, caching, calling external services, rate-limiting and periodically refreshing data.
Deploying the application to production, dealing with database migrations, and monitoring its use and performance.

You will learn from my experience in running, digitalizing, and growing a B2B industrial equipment trading business, for which in recent years I have implemented various small pieces of software in daily use, one of which, the ProductItems API is the precursor to what we’ll build in this book. In fact, what we are developing in this book mirrors partially what is in daily use at ISATEK .

What else will you learn?

My primary goal for you is to understand how to use Phoenix productively. However, through numerous “sidequests” we will exercise Elixir and Ecto skills that take you far beyond just learning to utilize Phoenix. We will use whatever is required to accomplish our objective. This includes the GenServer and Telemetry modules, Phoenix’s Live Dashboard (incl. Ecto metrics), accessing external services (e.g., to validate EU Tax IDs and fetch supplier company information), mocking external services with the Mox package for testing, and more!

The mindset is: if something could aid us in reaching our goal, we will try it out, no holds barred.

As with Northwind Elixir Traders , my side-goal with Phoenix Product Codex is to bolster your confidence and expand your research and development skills by helping you acquire an engineer’s exploratory mindset and grit in problem-solving. Therefore, you will also learn about:

the mentality and tools of working through a complex problem with pragmatism and an eye on managing complexity,
the gradual implementation of an ambitious and practical project that demands a certain high level of quality, and
the engineer’s mindset of dealing fearlessly with obstacles as they arise and aiming to deeply understand what’s going on, before rolling up your sleeves to deal with them.

What knowledge is required to get started?

A basic understanding of Elixir’s Kernel , in particular types of variables, flow control, the Enum module, how to define modules and functions, and how to write functional pipelines.
A basic understanding of relational databases and how they are structured (tables, columns and their types, primary and foreign keys), and of Ecto.
A basic understanding of how HTTP endpoints work, and the different request methods (GET, POST, etc.).
Truly rudimentary skills in running commands in a shell.

What will we not cover?

I assume that your interest in this book means that you already know how to install Elixir with your operating system’s native or package manager or with something like asdf , how to install the sqlite3 binary, and how to use an editor and IEx, so none of those topics will be covered.

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 or Excel-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 have been re-implementing everything cleanly using Elixir and Phoenix / Phoenix LiveView.

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.

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, and gradually accomplish all that by using everything at our disposal that makes sense–including any Hex.pm packages required, and any detours–in fact: detours are a key part of the exploratory approach. Thus, 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 else is in scope?

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!)

Where can I find more about this?

There is a discussion in the relevant forum thread on Elixir Forum.