Missed Opportunity: Phoenix needs a guide for creating REST APIs

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.

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.

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.

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/

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.

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.

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

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?

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

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.

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