CODEWITHSUNDEEP
sqlrestapi
Liutong Chen
Liutong Chen

Reputation: 3643

Should the response body of GET all parent resource return a list of child resource?

Please bear with me if the title is a bit confusing, I will try my best to explain my question below.

Say I have the following two endpoints

  1. api/companies (returns a list of all companies like below)

    [{name: "company1", id: 1}, {name: "company2", id: 2}]

  2. api/companies/{companyeId}/employees (returns a list of all employees for a specific company like below)

    [{name: "employee1", id: 1}, {name: "employee2", id: 2}]

What the client side needs is a list of companies, each one of which has a list of employees. The result should looks like this:

[
  {
    name: "company1", 
    id: 1, 
    employees: [ {name: "employee1", id: 1}, {name: "employee2", id: 2} ]
  },
  {
    name: "company2", 
    id: 2, 
    employees: [ {name: "employee3", id: 3}, {name: "employee4", id: 4} ]
  },    
]

There are two ways I can think of to do this:

  1. Get a list of company first and loop through the company list to make a api call for each company to get its list of employees. (I'm wondering if this is a better way of design because of HATEOAS principle if I understand correctly? Because the smallest unit of resource of api/companies is company but not employees so client is expected to discover companies as the available resource but not employees.)

a REST client should then be able to use server-provided links dynamically to discover all the available actions and resources it needs

  1. Return a list of employees inside each company object and then return a list of companies through api/companies. Maybe add a query parameter to this endpoint called responseHasEmployees which is a boolean default to be false, so when user make a GET through api/companies?responseHasEmployees=true, the response body will have a list of employees inside each company object.

So my question is, which way is a better way to achieve the client side's goal? (Not necessarily has to be the above two.)

Extra info that might be helpful: companies and employees are stored in different tables, and employees table has a company_fk column.

Upvotes: 3

Views: 1551

Answers (2)

Deva Gerald
Deva Gerald

Reputation: 334

I assume that the client you build is going to have an interface to view a list of companies where there will be an option to view employees of the company. So it is best to do it by pull on demand and not load the whole data at once.

If you can consider a property of your resource as a sub-resource, do not add the whole sub-resource data into the main resource API. You may include a referral link which can be used by the client to fetch the sub-resource data.

Here, in your case,

  • Main-Resource - Companies
  • Sub-Resource - Employees

Company name, contact number, address - These are properties of the company object and not the sub-resource of a company, whereas, employees can be very well considered as sub-resource.

Upvotes: 0

user7396598
user7396598

Reputation: 1289

Start by asking yourself a couple of questions:

Is this a common scenario?
Is it logical to request data in this way?

If so, it might make sense to make data available in this way.

Next, do you already have api calls that pass variables implemented? Based on your HATEOAS principle, you probably shouldn't. Clients shouldn't need to know, or understand, variable values in your url. If not, stay away from it. Make it as clean to the client side as possible. You could make a third distinct api "api/companiesWithEmployees" This fits your HATEOAS principle, the client doesn't need to know anything about parameters or other workings of the api, only that they will get "Companies with Employees". Also, the cost is minimal; an additional method in the code base. It's simpler for the client side at a low cost.

Next think about some of the developmental consequences: Are you opening the door to more specific api requests?
Are you able to maintain a hard line on data you want accessible through the api?
Are you able to maintain your HATEOAS principle in that the clients know everything they need to know based on the api url?

Next incorporate scenarios like this into future api design: Can you preemptively make similar api calls available? ie (Customers and Orders, would you simply make a single api call available that gets the two related to each other?)

Ultimately, my answer to your question would be to go ahead and make this a new api call. The overhead for setting up, testing, and maintaining this particular change seem extremely small, and the likelihood of data being requested in this way appears high.

Upvotes: 3

Related Questions