Labeling conventions in JSON API

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")}

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)

Why are those not consistent?

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

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 (Purely so that everyone knows where we stand - it’s not perfect, but it helps)