Proper way to provide a One-to-Many from an API?

Question

I've tried searching the interwebs and accept that I may be ignorant of the proper terminology required to find the solution. I'm OK with references to reading materials, but I'm not exactly sure where to start.

For the stack, I'm using Angular + NestJS. Plan to integrate TypeORM using Postgres as the database.

I have the following entities where a Budget has one Project and a Project may have many Budgets:

export interface Budget {
  id: number;
  description: string;
  project_id: number;
  budget_type: string;
  budget_status: string;
}

export interface Project {
  id: number;
  project_number: string;
  project_title: string;
  project_status: string;
  client: string;
}

For this scenario, I want to show a list of Budgets in a angular material table and show the "project_number" in the table instead of the "project_id".

Should I modify the Budget interface definition to return it's Project?

OR

Should I have the app request the Project resource through the API?

In general, for entities that hold references to other entities with an id. Should I include those entities in the response from the API or nest them into the response.

Should I modify the Budget interface definition to return it's Project? Concern: For more highly nested objects, there could be more data than what's actually needed.

{
    "budgets": [{
            "id": 1,
            "description": "platea dictumst",
            "project": {
                "id": 3,
                "project_number": "19139",
                "project_title": "neque aenean auctor gravida",
                "project_status": "Lost",
                "client": "Eabox"
            },
            "budget_type": "Change Order",
            "budget_status": "Approved"
        },
        {
            "id": 2,
            "description": "et commodo vulputate justo in blandit",
            "project": {
                "id": 78,
                "project_number": "19356",
                "project_title": "et eros vestibulum ac est",
                "project_status": "Active",
                "client": "Kimia"
            },
            "budget_type": "Original",
            "budget_status": "Lost"
        }
    ]
}

Should I have the app request the Project resource through the API? Concern: If I have 100 budgets, this would be an additional 100 calls to the API while the app is waiting for the table to load.

{
  "budgets": [
    {
      "id": 1,
      "description": "platea dictumst",
      "project_id": 3,
      "budget_type": "Change Order",
      "budget_status": "Approved"
    },
    {
      "id": 2,
      "description": "et commodo vulputate justo in blandit",
      "project_id": 78,
      "budget_type": "Original",
      "budget_status": "Lost"
    }
  ]
}

You can simply include project_number as well into the Budget interface. Use project_number to display in the table and project_id to reference the project entity.This way you can avoid additional read complexity. — Rajesh, Jan 14 '20 at 03:47
The Project/Budget relationship provided in the original question was only a simple example. I intend on adding more properties to the entities. Some of the objects that will be displayed in the list have multiple one-to-many relationships. — tunneling, Jan 14 '20 at 04:22

score 0 · Answer 1 · answered Jan 14 '20 at 04:33

I don't understand the array. You asked "Should I modify the Budget interface definition to return an array of Projects?" but "a Budget has one Project and a Project may have many Budgets".

You should not put the array of Projects into Budget. Also, since there is only one Project per Budget... I don't see how it'd be an array.

Here is some reading, but you want to list your entire Budget table. You want data from another table (not just the ID), so you can do a join. Here is a StackOverflow post on the types of joins. Here is an example that would get the project_number for an SQL query:

SELECT Budget.id, Budget.description, Project.project_number
FROM Budget
LEFT JOIN Project ON Budget.project_id = Budget.id

Since this can easily be done in SQL, you don't need to change your schema. When working with SQL you should prioritize one-to-many over many-to-many and you should use the key from the "many" to point to the "one" as you have done.

Thank you for your response. SQL is not the issue. My question is more about implementation of the API. Do I send the Project nested in the Budget.. or do I perform another hit on the API to get the Project after the Budget has been received by the app. — tunneling, Jan 14 '20 at 05:05
Also, you're right. I mangled up the description. I was thinking about the reverse. If I was going to request the Projects from the API.. would I just send the 'id' of other entities to the app OR should I include the entities in the response. — tunneling, Jan 14 '20 at 05:09

Proper way to provide a One-to-Many from an API?

1 Answers1