CODEWITHSUNDEEP
c#restasp.net-web-apiurl-routingasp.net-core-webapi
Ish Thomas
Ish Thomas

Reputation: 2440

Update an Entity with the Collection

I'm having a problem to find a standard, how such an update would look like. I have this model (simplified). Bear in mind that Team is allowed without any player and Team can have up to 500 players:

public class Team
{
    public int TeamId { get; set; }
    public string Name { get; set; }
    public string City { get; set; }

    public List<Player> Players { get; set; }
}

public class Player
{
    public int PlayerId { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

and this endpoints:

  1. Partial Team Update (without players): [PATCH] /api/teams/{teamId}. Offers me options to update particular fields of the team, but no players.

  2. Update Team (with players): [PUT] /api/teams/{teamId}. In payload data I pass json with entire Team object, including collection of players.

  3. Update Player alone: [PUT] /api/teams/{teamId}/players/{playerId}

I started wondering if I need endpoint #2 at all. The only advantage of endpoint #2 is that I can update many players in one request. I can delete or add many players at once, as well. So I started looking for any standard, how such a popular scenario is being handled in the real world?

I have two options:

  1. Keep endpoint #2 to be able to update/add/remove many child records at the same time.
  2. Remove endpoint #2. Allow to change Team only via PATCH without ability to manipulate Player collection. Player collection can be changed only by endpoints:
    • [POST] /api/teams/{teamId}/players
    • [PUT] /api/teams/{teamId}/players/{playerId}
    • [DELETE] /api/teams/{teamId}/players/{playerId}

Which option is a better practice? Is there a standard how to handle Entity with Collection situation?

Thanks.

Upvotes: 1

Views: 155

Answers (1)

Athanasios Kataras
Athanasios Kataras

Reputation: 26362

This one here https://softwareengineering.stackexchange.com/questions/232130/what-is-the-best-pattern-for-adding-an-existing-item-to-a-collection-in-rest-api could really help you.

In essence it says that POST is the real append verb. If you are not really updating the player resource as a whole, then you are appending just another player to the list.

The main argument with which I agree, is that the PUT verb requires the entire representation of what you are updating.

The patch on the other hand, I would use to update a bunch of resources at the same time.

There is no really wrong or right way to do it. It depends on how you view the domain at the end of the day.

You can have bulk operations and I would certainly use POST with that. There are some things to consider though.

  1. How to handle partial success. Would one fail the others? If not, what is your response?
  2. How will you send back the new resources url? The new resources should be easily discoverable.

Apart from some design considerations, if you are taking about multiple inserts, you'd better do it in bulk. If it's a couple at a time, save yourself and the people who will consume it some time and go with one by one.

Upvotes: 1

Related Questions