I just finished a full step-by-step tutorial on how to build a JSON API with Phoenix:
- Create a new API-only Phoenix application —skip HTML and JS stuff.
- Create a User schema module (model) and hash its password —because storing plain text passwords in the database is just wrong.
- Create a Users endpoint —so you can get a list of, create or delete users!
- CORS configuration —so you can use that frontend of yours that runs on another port / domain.
- Create a Sign in endpoint —using session based authentication.
Any feedback is appreciated!
P.S. Please bear in mind I’m just starting with Elixir and Phoenix. But did my best to try to make it as clear as possible for advanced users from other frameworks (like Rails).
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?
From the article:
defmodule MyAppWeb.Router do
scope "/api", MyAppWeb do
resources "/users", UserController, except: [:new, :edit]
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
resources "/users", UserController, except: [:new, :edit]
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: https://pragmaticstudio.com/courses/unpacked-multi-player-bingo-with-elixir-phoenix-vue-elm
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.
(note, by the way, that there’s nothing structurally wrong with Phoenix/Ecto but the defaults - it’s not as bad as an entanglement as Rails/ActiveRecord. I just wish that there was a way to whip up a default Phoenix project that was multi-application, not made for a single simple website but to grow into something more complex, neatly separating concerns; maybe as an umbrella - http servers and database I/O just don’t belong in the same spot, and OTP makes it trivial to separate them out; it should be made the default somehow)
You can achieve that by simply passing a flag to phx.new:
mix phx.new --umbrella my_app
And then if you need an app that doesn’t talk to the database:
mix new some_api_client
Those capabilities have been there since v1.3. It is not a default but it is definitely promoted as part of Phoenix as a first class concept.
There have been plenty of discussions on why it isn’t the default so maybe someone can post a link to those (in a nutshell, dropping users into an umbrella project without any context may confuse more than help). We also plan to explore and discuss it in the upcoming Phoenix v1.4 book update too.