Tutorial: Building a JSON API with Phoenix 1.3 and Elixir

Thank you, this is just what I need to start, as most tutorials are focusing on full stack.

You’re planning to use JWT, but do you have any recommendation for LDAP bindings for elixir?

There is native support in erlang. Here’s a good tutorial. http://rny.io/elixir/phoenix/ldap/2016/09/20/ldap-authenication-with-phoenix.html

From the article:

defmodule MyAppWeb.Router do
 # ...
 scope "/api", MyAppWeb do
   pipe_through :api
   resources "/users", UserController, except: [:new, :edit]
 end
end

I don’t understand why an API endpoint is under a web layer?

Web endpoints in my point of view should only return html.

When defining API endpoints, that normally return json, they should go under an API only layer, because they are two separate concerns. An API can be used by a mobile app, a web app, an IOT device, another micro-service, etc.

I would expect something more like this:

defmodule MyApi.Router do
  # ...
  scope "/api", MyApi do
    pipe_through :api
    resources "/users", UserController, except: [:new, :edit]
  end
end

That’s being extremely pendantic.

Maybe because being web means it speaks HTTP?
Just think about it for a minute, I think you’ll find it makes sense.

Its just a module name, feel free to use whatever you want.

Take a look at the documentation of Phoenix.Router.scope/2 where they use API.V1 as an example alias.

No I am not being pedantic with the name choosen for the Module if that is what you are referring to.

because they are two separate concerns. An API can be used by a mobile app, a web app, an IOT device, another micro-service, etc.

As I said in the because bit an api can be consumed by many different clients, thus my concern is about separation of concerns and software architecture.

The tutorial seems to be based on the Phoenix structure that mixes endpoints for a web app with REST API api can be consumed by many different clients, thus my concern is about separation of concerns and software architecture.

The tutorial seems to be based on the Phoenix structure that mixes endpoints for a web app with REST API endpoints… by their docs it seems that way, both api and web endpoints under same folder lib/myapp_web. Am I misunderstanding something?

Keeping all this endpoints mixed is contra-productive in the long run for a software you release in production… I learned this lesson in the hard-way and now that I separate them is much more easy to maintain, add new features, less prone to bugs and more easy to onboard junior developers. Can take you more hours to develop but saves lots of hours more in the long run.

Now for a pet project is fine to have all mixed once they are normally to throw away once you are done with learning some features you are interest in. For a prototype I would not recommend to mix the endpoints, once they tend to end-up in production.

This is my point of view based on my experience… You may have another view and I love to discuss them, because we always learn something new

Let’s start by me stating that I think that Phoenix is full of antipatterns, apparently to appease the Rails crowd (who apparently thrive on doing things in the worst possible way). A big one to me is this split of an application in “foo_web” and “foo” submodules(?) instead of a “foo_web” application sitting next to a “foo” application. We’re splitting it up these days, much nicer.

What I also don’t like is the wording “web” for “HTTP endpoint/server”. It is confusing and indeed doesn’t help these sorts of discussions. Just call it what it is, much simpler. “foo_http_endpoint” and “foo”, or something like that.

Having said that, you have a single logical HTTP endpoint (one port), and the responsibility of that thing is dispatching incoming requests to the correct handler. In that sense, having a single Router is nice. You see in one view what all the possibilities are and as long as all that the router does is dispatch to the correct handler (controller), it’ll never get too long.

The controllers, then, are the point where you may want to start to differentiate between controllers for API, for a browser UI, for mobile, … Again, you can make a valid argument that this should all be separated, and I’d separate it into separate applications.

I usually find most Elixir code quite readable, but not Phoenix code. I think that the insistence on bundling up everything in a single OTP application does not help. Phoenix should probably generate an umbrella instead, which would make separating mobile controllers from API controllers (etcetera) much easier. Trivial, in fact.

Well, you can really architect your app whatever way you want, and Phoenix doesn’t stop you from doing it the right way.

This is beautifully illustrated here: Unpacked: Multi-Player Bingo with Elixir, Phoenix, Vue, and Elm | The Pragmatic Studio

I know. Neither does Rails. But it’s work to get there and now you’ve deviated from the defaults and the stuff in the docs and books so new people are all WTH? when they look at the result. And you spent $$$$ to fix stuff that shouldn’t be wrong in the first place.

I’d rather have the defaults be correct (for scaling up, not in requests-per-second, but in complexity) so Joe or Jane A. Coder has a better chance of getting it right and ramp-up of new members on a project is simple.