Best practice for phoenix project with HTML and JSON endpoints

Hi all,

I’m starting a new project where I am planning on having both JSON and HTML endpoints. I’ve been looking into some of the best ways to prevent code duplication across two separate sets of controllers, one for each response type. I think this might be the most straightforward way of going about having both an API and regular web endpoints, but I wanted to ask and see if there is a better recommended way of doing it.

I noticed that I can let Phoenix decide which templates to render by passing an atom to the template name in the render function instead of a string, which I think is pretty cool and would be a good way to achieve this goal. An example of this would be render(conn, :index, users: users) instead of separately having render(conn, "index.html", users: users) and render(conn, "index.json", users: users).

I have tested this out, and it works well. However, the main issue I am running into is with the html-specific parts of the controller. In the case of my very very simplistic test project, I experience errors on any API calls to put_flash/2 or if there is an error with the changeset and a redirect to the new or update pages (which obviously don’t exist for the json endpoint). Is there a simple way to structure this such that I can get around these html-specific lines?

I think my options would be to pattern match on the connection and have two separate controller functions (not ideal, logic duplicated) or to have separate controller modules entirely (also not ideal, duplicated code). If the best practice is to separate controller modules, what is the best file/naming structure for this?

I noticed this question is similar to this post, but since it has been 3 years since it was posted I wanted to see if there is an update or consensus to this answer.

Thanks!

TL;DR

Best practice for controllers that can render both JSON and HTML?
How to not break JSON endpoints that have calls to put_flash/2 and other html-specific functions?
If splitting up controllers is the best practice, what should file naming convention be? And project organization? (file structure like project_web/controllers/api/user_controller.ex and project_web/controllers/html/user_controller.ex or something different?)
a link to an example project on GitHub that does this would be a great bonus

7 comments

/phoenix #best-practices #project-structure

25 5112 7

2022-02-24 13:53:23 UTC

Marked As Solved

egze

I would structure it like this:

html:
project_web/controllers/user_controller.ex

api:
project_web/controllers/api/user_controller.ex

You are much more flexible this way, instead of keeping it in one controller. For example:

you may (and probably should) have different pipelines for html and api controllers in your router.
you may use some api documentation library for Swagger. Then your html controller still stays clean.
complexity is lower, no need to worry about preparing a response based on html or json format. you just know that api controllers send json and that’s it. Testing as a result is also simpler.

Post #3

Also Liked

Yunus

Of course after finally asking here, I found the answer.

mix phx.gen.html Accounts User users name:string
mix phx.gen.json Accounts User users name:string --web api (and delete the extra migration)

With the --web api argument it’ll create the files in web/api and you can do MyApp.Api.UserController.

Post #7

akashv

I stumbled here a little late, but you can skip additional schema and context creation by appending --no-context and --no-schema to your phx.gen.json command. This will only generate api controllers and views in the api folder (as per namespace)

Post #8

Qqwy

TypeCheck Core Team

This is a more general response, but I believe that the predominant pattern in situations like this is to extract most/all logic from the controller-layer to an intermediate ‘domain’ layer, which is shared by the HTML- and JSON-controllers. This approach is known as ‘domain-driven-design’.

The only thing the controllers then do is to be ‘traffic cops’ redirecting the flow to/from the functions in these domain layer, and transform e.g. error responses from the domain layer to an appropriate response in the current format: for HTML you might show a flash-message whereas in the JSON-API you might want to replace the normal response with something akin {"status": "error", "message": "This was the problem"}.

Post #2