RESTful API – Should It Provide Data for an Entire Form?

apiformsrest

Let's say I have a JavaScript web application which entirely uses a RESTful API for data.

Let's say this application has a data form, and let's say I'm editing a record at /product/12345. When building the form, I make a RESTful request to /product/12345 and get JSON data:

{
  "id": 12345,
  "name": "Some Product",
  "active": true,
  "sales_user_id": 27
}

So, my form obviously may have a dropdown list for selecting a sales person. I need to populate this list. Where should the data come from? What's the most common approach?

Would it make sense to make it part of the /product/12345 request response?

{
  "id": 12345,
  "name": "Some Product",
  "active": true,
  "sales_user_id": 27,
  "sales_users": [
    {"id": 1, "name": "Anna Graham"},
    {"id": 2, "name": "Dick Mussell"},
    {"id": 3, "name": "Ford Parker"},
    {"id": 4, "name": "Ferris Wheeler"},
    {"id": 5, "name": "Jo King"}
  ]
}

What about when creating a new record? Should my API also respond to GET /product/new, with the following?

{
  "sales_users": [
    {"id": 1, "name": "Anna Graham"},
    {"id": 2, "name": "Dick Mussell"},
    {"id": 3, "name": "Ford Parker"},
    {"id": 4, "name": "Ferris Wheeler"},
    {"id": 5, "name": "Jo King"}
  ],
  "categories": [
    {"id": 1, "name": "Category 1"},
    {"id": 2, "name": "Category 2"},
    {"id": 3, "name": "Category 3"},
    {"id": 4, "name": "Category 4"},
    {"id": 5, "name": "Category 5"}
  ],
  "etc": [ ... ]
}

Best Answer

I lean towards very simple, narrowly-focused endpoints. I would expect a request at some location like /sales_users which returns all sales users.

GET /sales_users:

[
    {"id": 1, "name": "Anna Graham"},
    {"id": 2, "name": "Dick Mussell"},
    {"id": 3, "name": "Ford Parker"},
    {"id": 4, "name": "Ferris Wheeler"},
    {"id": 5, "name": "Jo King"}
]

Similarly, if you are going to have a list of categories, I would add a separate endpoint for that.

GET /categories:

[
    {"id": 1, "name": "Category 1"},
    {"id": 2, "name": "Category 2"},
    {"id": 3, "name": "Category 3"},
    {"id": 4, "name": "Category 4"},
    {"id": 5, "name": "Category 5"}
]

I would not build a GET /product/new. Rather, I would build a form in your app to handle adding new products which knows the appropriate requests to populate its lists (e.g., GET /categories, GET /sales_users, etc.).

Related Topic