I think people that think REST API responses are fundamentally different from html responses don’t really understand the ‘R’ in REST ¯\(ツ)/¯
But, yeah, I’m open to a PR improving the docs. 
2 Likes
Thanks for thinking of us @AstonJ 
We’ve been discussing Phoenix lessons and would welcome input from others.
@chuck what things specifically would you like to see covered? I’d be happy to set aside some time for a blog series to help yourself and others until we can formulate a plan for actual lessons (and translations).
If you’re interested in collaborating together let me know! Always happy to help folks 
8 Likes
Ideally, there would be complete end-to-end documentation for Phoenix for API developers. It wouldn’t assume any knowledge of Phoenix. It would be updated to reflect any changes introduced by new releases of Phoenix, i.e. it should be supported.
A lower effort alternative would be parallel sections in the current documentation with information specific to API developers.
An even lower effort alternative would be a separate guide devoted to API development.
I would and may help with these eventually, but right now I’m not far enough along on the learning curve myself.
2 Likes
I’m still wondering what would people like to have in there content wise?
2 Likes
I think they will need more specifics. Since I’m on the same boat as you - Learning Elixir and Phoenix while developing Web APIs - I’ll try to help:
It’d be great if the Phoenix guide have a section on Web APIs. This will save us time as we don’t have to find the info inside the Views section.
That section should start by stating that a great way to start is by running the generator with the no-html and no-webpack options.
It should also mention that if you’re not using a database and you don’t need bi-directional communication, you might consider not even using Phoenix at all as Elixir, Plug, Cowboy and Jason should be sufficient.
Then, it could mention that other stuff you need is the same as regular Elixir development, e.g. Supervisors, GenServers, ETS, CacheX, CVS and/or XML parsing, etc.
That’s a very short summary of what I have learned. What do you think? Am I forgetting anything important?
4 Likes
What does this mean to you though? What are the specific topics you’re not clear on? “Complete documentation” means something different to everyone who reads it.
Are you looking documentation down to what JSON and an API are? I’m trying to get a sense of how granular you’re looking to go.
If you were going to write a book for developing JSON APIs, what chapters would it have to have?
1 Like
We’re working on a blog series over at elixirschool.com on this very thing! The first post does focus on HTML just to illustrate how simple that can be without Phoenix but there is a small section on using JSON: Building web apps with Plug.Router | Blog · Elixir School. Next post will cover deploying our sample application to Heroku followed by a post series focused on building JSON only API using Plug.Router. I’m sure we can find a way to work in a post on using Phoenix for the same task.
I’m not sure this fits in a guide to developing JSON APIs though. We have most of this content on elixirschool.com already. Maybe we would benefit from a section focused on apply of these concepts?
We started on a repo of partial projects that you can finish yourself to explore Elixir but it could certainly be improved: GitHub - elixirschool/homework: A collection of coding exercises to be completed in conjunction with the lessons available on elixirschool.com
1 Like
I was just suggesting that the Web API section should state something like “from here on is the same as any other Elixir app”, or “For all these subjects, see their specific sections”. It’s just to emphasize what everyone keeps telling you the first time you ask the question which is: “there’s no really much difference” 
Perhaps, the question won’t be asked this often then.
Great news about the new upcoming content. Keep up the good work
4 Likes
I gotcha! Just to reenforce to the reader that from here on out it’s Elixir as usual, the API part is “over”.
Thank you! If you have any suggestions for content or changes we’re all ears
Imagine everything taken out of Phoenix that pertained to rendering the user interface layer. All that is left is the capability to develop REST APIs. Now think of how you would document just that? The documentation would be a lot smaller than the current documentation, but there would still be a lot to document.
Definitely you would assume that your readers are very knowledgeable regarding JSON/REST APIs. That’s why they are looking at Phoenix (lite) in the first place.
Exactly. This question appears so often here, and on other sites/forums. That I think it should be answered asap.
Great. Let me collect my thoughts, and I’ll send those directly to you guys. Also, I hope to have more in the future
2 Likes
This is the problem: the community (and Phoenix guides) have documented building a JSON API how I would. That’s why I’m looking for specifics so we address the gaps. That’s the difficulty I think we’re all having here: without specifics about what is missing, the current documentation seems sufficient to those of us reading them.
Just trying make sure we can effectively help you rather than produce more documentation that fails to meet your needs.
We’ll kick around some ideas.
We definitely can’t assume that which is why I ask. I can tell you from first hand experience through elixirschool.com we get folks coming to Elixir who’ve never ever programmed before and are looking for this to be their first language.
7 Likes
Well, you can build a SOAP APIs as well, no?
How would you do it? I got the feeling that people would like to help you, but you’re not being specific. Can you provide one example of what you found difficult while learning what you know now? That might help us all understanding your point of view
1 Like
You definitely can assume that there are a tremendous number of organizations that are looking for a platform for building JSON/REST APIs that offer the performance and reliability that Elixir/Phoenix can offer. They know all about REST. They like to talk about SOA and micro services. My guess is that this audience is significantly larger than the one what wants to develop monolithic web apps.
I agree 100% that there is sufficient information in the Phoenix docs and in the various tutorials to build build JSON/REST API apps. But that information is widely scattered and takes a back seat to the other Phoenix use case. The API use case is definitely not emphasized. My suggestion is to add a guide to the current set of Phoenix guides that promotes, documents and emphasizes the API use case.
4 Likes
I also found Phoenix’s lack of API tutorials a sticking point. I am not interested in doing frontend work in elixir, only for API use. And so it took me an embarrassing amount of time to discover that I could return answers like so in a controller
def success(conn, m) do
conn |> json(m |> Map.put(:success, true))
end
def failure(conn, code, message) when is_integer(code) do
conn |> put_status(code) |>
json(%{success: false, message: message})
end
I’m still not entirely sure I’m doing it right to be honest. In particular the render method that is used everywhere was really confusing to me. I’m not sure why I would need what appears to be a template rendering function that references a filename to render json.
7 Likes
I can see that calling it render might be misleading, but Phoenix.View’s are not about template rendering per se. In fact all the template rendering functionality comes from Phoenix.Template (see the render_template I showed here) and it just happens to be one of the things a view does as part of it’s job.
Phoenix.View’s are about mapping the data your controller aggregates to the format they’re returned in as the response of the http request. And that’s needed for any kind of response be it an html page, a json document, a xml document or any other one you might be using. Some of them might be created using templates others might not. Granted for json documents it can be as easy as just encoding the data as is, but it’s not always that easy.
Like you might have a user struct and in one place you like to encode it with information about the user being an author (name and num. of publications), while at another place the same user struct might be encoded for authorization purposes (e.g. role and permission information). This is logic phoenix wants you to put into a View and not do it in controllers. The controller should just care to retrieve the user struct.
Another thing you might do in a view is hide specific fields. Like for an access controlled file you might not want to hide the password a user needs to download it. Again the controller is for the data retrieval, but not for knowing how to modify the data for sending in the response.
Edit:
The filename (e.g. “index.json”) is more of a “render the “index” json document with data …”. The filename format just makes it super convenient if you happen to use templating.
5 Likes
Can you provide an outline for how you would structure this new guide? A list of bullet points would be great. I think people are trying to help you but you aren’t giving them much to go on by just saying:
3 Likes
A couple of quick things.
First, there is a treatment of the mix task for generating a JSON resource in the Mix Tasks Guide.
There is also a link to the Mix Tasks Guide pretty early on in the Up and Running Guide, at the bottom of the first group of block quotes.
Seems like a reasonable solution might be a quick paragraph in the Up and Running Guide pulling all of these parts together - the mix task and the view/rendering information.
4 Likes
Btw, it was fun reading some of this material again after a while away from it. I can recognize my own voice in much of this, but it’s great to see so many additions by other folks. 
4 Likes
Just dropping this here…
10 Likes
