Missed Opportunity: Phoenix needs a guide for creating REST APIs

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.

19 Likes

You have the book Craft GraphQL APIs in Elixir with Absinthe, it uses Absinthe (a GraphQL implementation for Elixir), which is an interesting alternative to REST for creating modern APIs.

In the end, if you know MVC, then you’re good to build an API, APIs are just MVC without the view part.

8 Likes

We are looking carefully at GraphQL. It seems to be gaining steam. However, our GUI teams are sticking to REST for the time being. That is what they know and are comfortable with. We’ll be in the REST API business for quite a while I think.

2 Likes

At my job we only use phoenix for JSON apis (no html rendering or templates or anything like that). I could totally see the benefit of providing some guides specifically for that. As written the guides are geared to showing all the things that phoenix provides. REST Apis are discussed in the guides IIRC. But having them be their own section seems like it might not be a bad thing. I feel pretty confident that if someone wanted to do that work the phoenix team would be happy to accept it.

12 Likes

The first hit for a google search on phoenix api is a good api tuto, covering testing as well…

… and Phoenix 1.4

https://lobotuerto.com/blog/building-a-json-api-in-elixir-with-phoenix/

11 Likes

So I’m not doing a lot of api stuff, but the only thing different for an api is how data is rendered. The guides about the view layer in elixir has a section on rendering JSON. What else would there be needed for a REST api? I’ve also just looked at a handful of documentations for other frameworks and non of those explicitly detailed REST apis, but rather the higher level concepts by which they operate.

2 Likes

This, actually, might be the best resource out there. At one point, it was out of date, but it looks like it has recently been updated. Don’t miss my point though. I’m not saying there isn’t suitable documentation out there. It is spread throughout the guides and present in the various tutorials that can be found via google. What I’m saying is if there was a good guide present in the guides, there would be a lot more people getting interested in Phoenix for API-only development. Being a recent and enthusiastic Phoenix adoptee, I would like that.

10 Likes

As I’m pretty new to Elixir/Phoenix my thoughts:

  1. After making the decision to start with Phoenix and Elixir https://phoenixframework.org/ is the starting point for most people.

  2. Prominent placement on the side “get up and running” -> like RoR, not bad for people coming from RoR to see that both frameworks have a lot in common, for other people: Phoenix is easy.

  3. Title of the link: “Build APIs, HTML 5 apps & more” - perfect (especially in this order) - here is my personal BUT…: going to the same page (getting started). When you are looking at the guides there it is about the main concepts like “adding pages” (2nd guide), … - I would go from the prominent main link to a very simple page with “see some basic examples of: REST API, GrapyQL API, web app with server rendered pages, the beauty of long running requests, channels, …” and probably ask some people with the best tutorials if we can put the links in there (or write some according to wishes from the core team & community). a) not all people are googling, some actually like following the links and b) not all tutorials you find are up to date or good. So for me it’s easy now to find a good tutorial, but if you begin and are running in an outdated one that definitively gives you a much harder start.

  4. Apart from that: google, books and especially the community are great, imho nothing to change here :slight_smile:

Short summary of my opinion:

  • Starting page: " Productive. Reliable. Fast." - great
  • Prominent link title: " Build APIs, HTML 5 apps & more" - perfect
  • would opt for a page that shows some quick examples that prove the claims
  • Rest: perfect as it is

Ideally the small examples show some highlights of Elixir because I think most of the people coming here are new to both, the language and the framework. Can we deliver a 30m to 4 hours example for the real world cases with the wow effect that we all got after some hours to days of googling where we hide small gems (not RoR ones) that make the daily life so much easier?

5 Likes

The view still exists, it just renders the output in a different format (XML, json, text, …)

It’s as simple as

defmodule MyApp.Router do
  use MyApp, :router

  scope "/api", MyApp do
    pipe_through(:api)

    resources "/items", Api.ItemController
  end
end

defmodule MyApp.Api.ItemController do
  use MyApp, :controller

  def index(conn, params) do
    items = Context.list_items(params)
    render(conn, "index.json", items: items)
  end
end

defmodule MyApp.Api.ItemView do
  def render("index.json", assigns) do
    assigns.items
  end
end
1 Like

Going to chime in to say that the lack of direct API demos was a major irk for me when beginning with Phoenix. Also, there’s a strong bias towards tutorials assuming familiarity with Ruby on Rails – which, coming from other tech, was not a straight forward or happy feeling.

I’ve really enjoyed Elixir for everything except the web stuff.

11 Likes

I’ve never really understood the utility of dispatching on a string (“index.json”) in the views when building REST APIs. What’s the advantage over directly calling a function like this?

defmodule MyApp.Api.ItemController do
  use MyApp, :controller
  alias MyApp.Api.ItemView

  def search(conn, params) do
    items = Context.list_items(params)
    ItemView.render_many(items)
  end
end

defmodule MyApp.Api.ItemView do
  def render_many(items) do
    items # or whatever logic
  end
end
4 Likes

There are a few things Phoenix.Controller.render does for you:

  • It merges your data with the current assigns and converts the result to a map
    (views don’t support keyword lists)
  • It does automatically set the content type for you
  • It does dispatching to layout views if you use them
  • It calls the view functions, which return iodata, so it can benefit from the performance gain of not building large binaries
  • It sends the templated data as response

So it’s basically a shortcut to remove a bunch of boilerplate you’d have to write on your own otherwise.

4 Likes

I’m referring to the directory of the templates, the real V of MVC which the user will interact. Phoenix.View is coupled to the framework and you’ll need to use it whenever you create a MVC app or an API, as it’s required in order to render / expose data just like you’ve said.

In other frameworks the type of data returned is specified inside the controller (sometimes globally inside the core of the app) or detected by the framework itself. So, I believe that Phoenix.View acts like an extension of the controller either by interacting with the template or just by specifying the data to return, and that’s a bit confusing (correct me if I’m wrong, but that’s what I guess from my experience). If I’m right I’ll love to know why Phoenix exposes this “views” directory instead of doing everything from the controller.

Most of the time in a normal MVC app the “WhateverView” module is almost empty, I just use it for defining a title.

That’s is because of EEx, which actually compiles templates into functions of the view module. The compiled project only has modules and no template files anymore. This makes it quite a bit faster than frameworks without precompiled templates. That’s also why json and html views actually work with the same api even if one is using written out render functions and the other is using templates. Both are called using render/2 on the view module.

You could even use the render function to e.g. prepare date for the template:

def render("show.html", %{date: date} = assigns) do
  data = %{assigns | date: Date.to_iso8601(date)}
  render_template("show.html", data)
end

So the view is hardly as useless as the mostly empty modules make it look like. It’s more due to the fact that phoenix is compiling the 95% use-cases so efficiently into the module that often times you don’t need to modify it. But if you do to you can.

You can do the same in plug/phoenix as well: json(conn, data). But it means your data must be json-encodable by globally defined rules. This get’s problematic as soon as you want to have more than one json representation based on the same data. If you want to work around that limitation just in the controller you’d put a lot of data mapping logic into the controller, while phoenix simply encourages to put all that logic into a view module right from the start (which is also where it really belong).

3 Likes

We do have a section about rendering JSON for apis in the guides:

https://hexdocs.pm/phoenix/views.html#rendering-json

If someone would like to expand on this and/or make it more discoverable, we would love a guide contribution. Thanks!

16 Likes

I marked Chris’s post as the solution for this thread :003:

2 Likes

This is certainly a very nice feature of EEx but it is not the reason to separate Views from Templates/Controller.

@adrianrl
I believe the reason is to separate template helpers (something like format_date that would be defined in the View module) from other functionality that lives in the controller.

In my experience I have found that I want to reuse most view helpers across more than one template and so my View modules are normally pretty empty, me helpers end up in some other utils module.

Just to demonstrate that compile time templates do not require a view, here is an example what I am doing with a Raxx project I have

defmodule MyApp.ShowUser do
  use Raxx.SimpleServer

  use Raxx.View,
    arguments: [:user],
    template: Path.join(__DIR__, "show_user.html.eex"),
    layout: Path.join(__DIR__, "_layout.html.eex")

  def handle_request(_request, _config) do
    user = get_a_user()

    response(:ok)
    |> render(user)
  end
end

The template is read and compiled once, and everything lives in MyApp.ShowUser.

3 Likes

Respectfully, I don’t think that Chris’ post is a solution to the thread. Imagine yourself in the position of being completely new to Phoenix and possibly Elixir. Perhaps you have no experience with rails either. Their goal is to learn Phoenix with the express purpose of evaluating it for REST API development. If you proceed through the Phoenix docs or through the “Programming Phoenix” book, there are brief mentions of API creation, but those mentions are obviously far overshadowed by the main theme of the documentation - building self contained web apps with server rendered html.

I’ve heard it dismissively said that Phoenix produced JSON APIs are trivial and are merely JSON views or something to that effect. And perhaps the development of JSON APIs are very easy compared to developing a self contained web apps. All the better. But people that say this already have a very complete understanding of Phoenix. It’s entirely possible that someone new to Phoenix has no real concept of Phoenix endpoints, controllers, views, routers, templates, etc. To tell them that Phoenix API development consists merely of JSON views is meaningless.

My point is simply this. I think if there were an officially supported Phoenix guide for developing REST/JSON APIs, Phoenix’s user base would be increased and this would be a good thing for Phoenix and Elixir.

18 Likes

I’ve heard it dismissively said that Phoenix produced JSON APIs are trivial and are merely JSON views or something to that effect.

I think that’s because mix.gen.json makes it so easy to scaffold a basic REST API, and if you got how to use phoenix html, it boils down to understanding how to write tests in elixir, ecto and maybe a few other components more than anything. That might lead people to “dismissively say” that :slight_smile:

My point is simply this. I think if there were an officially supported Phoenix guide for developing REST/JSON APIs

I am not really opposed to that, but I feel like it would be almost exactly the same as the “regular” guide - which already includes a part talking about rendering JSON.

What about this bit:

Perhaps you can help create such a guide if you feel the current one is lacking? You could post in the #your-libraries-projects:projects section to seek others who might be able to help? Perhaps @doomspork and the ElixirSchool folks might be able to offer their assistance or maybe create a section for such tutorials as well?

The great thing about the Elixir community is that it’s quite possible you’ll be able to find someone who shares the same idea, and may be willing to help. And if you can’t… our community is very receptive to ideas on on-boarding and adoption, so you’re only as limited as your skills of persuasion :003:

5 Likes