Let me start by stating an assumption: Phoenix is a great approach to building REST APIs. There are many reasons for this, but I will assume that those on the forum understand why this is so.
Now assume that a team that needs to create a new REST API has heard about the performance and reliability characteristics of Elixir, and after a little research they come upon Phoenix as an implementation candidate.
Being new to Phoenix, where do they start their research on evaluating Phoenix as a candidate? They will start with the Phoenix guides of course. Sadly, they don’t get very far until they wrongly conclude that Phoenix isn’t what they are looking for. They will conclude that Phoenix’s primary use case is developing monolithic web applications using server rendered HTML. I am sure this has happened because that is what happened to our team. The person charged with evaluating Elixir/Phoenix reported to the team that Phoenix didn’t seem like a good fit, roughly stating the conclusion just described.
Luckily, another person on the team was really impressed with Elixir in general and so chose to do his own evaluation of Phoenix. Again, this person started with the Phoenix guides and again found that it wasn’t a great place to start if one is only interested in using Phoenix to build REST APIs. Our team doesn’t care much about GUIs. We develop REST APIs that are consumable by other teams that build mobile and desktop clients.
So this person resorted to googling for help and found a variety of helpful articles. However, the articles did have some problems. They were often out-of-date and/or incomplete. But he slogged through it. He read through the articles and the Phoenix guides. He also did a lot more googling for additional helpful articles.
The good news is that we have chosen to develop some new REST APIs using Phoenix. The bad news is that had it not been for our stubborn team member we would not have chosen Phoenix or for that matter, Elixir.
There are literally thousands of API teams out there that would be thrilled with the performance, reliability and the pure coding enjoyment of Phoenix/Elixir. If the Phoenix team were to write a guide for this Phoenix use case, I am sure that many of them would choose Phoenix.