Labeling conventions in JSON API

Phoenix Forum Questions / Help
1

When I generate a JSON API using the mix phx.gen.json task, the output (in the view) is labeled as “data:”

  def render("index.json", %{users: users}) do
      %{data: render_many(users, UserView, "user.json")}
  end

but examples tend to use the object name (in this case “user”) for the input.

 def update(conn, %{"id" => id, "user" => user_params}) do
     user = Accounts.get_user!(id)
      ...
 end

Why are those not consistent?

2

It’s pretty typical for a JSON API to render an array in an envelope. Most use a generic key for this, data.

3

If I had to guess, it would be because when you are fetching something (as in the first example) then you want to know what the data is, any errors and any metadata, so wrapping those in their own envelope keeps them separate.

%{
  data: render_many(users, UserView, "user.json"),
  errors: ...,
  meta: ...
}

When you are updating (as in the second example) then you are mostly updating a single object, so it doesn’t necessarily make a lot of sense to wrap it, as you are passing related data only.

Having said that, If I have to do a JSON API then I personally prefer to follow the spec at http://jsonapi.org (Purely so that everyone knows where we stand - it’s not perfect, but it helps)