REST API redundant path parameters

Question

I'm wondering about best practice when designing the URIs for your REST API that contains resources with relationships between them.

I have 2 entities; Team and Player, and these URIs:

GET  /teams                   <- list teams
GET  /teams/{id}              <- get single team
GET  /teams/{id}/players      <- list players in a team
POST /teams/{id}/players      <- create a player and add to it to the given team

Now here's my question; the player being created through POST /teams/{id}/players will have its own ID (a UUID) and live as a row in its own database table. This means that getting this player will have 2 alternative URIs that contains the necessary information for GETing this resource back:

 GET /teams/{id}/players/{id}  <- returns PlayerDto
 GET /players/{id}             <- returns PlayerDto

This really confuses me as the team ID will be redundant in the first case, wouldn't it?

It does however make more sense if you have two separate resources returned by the endpoints, for example:

GET /teams/{id}/players/{id}   <- returnes TeamPlayerDto, which contains contextual information for the player in the given team
GET /players/{id}              <- returns PlayerDto, which contains general information about the player, like which teams he has belonged to throughout his career

In your opinion, what makes more sense in this case? Is GET /players/{id} sufficient if you only have a single representation (like PlayerDto) for your resource?

score 0 · Accepted Answer · answered Dec 18 '22 at 14:24

Now here's my question; the player being created through POST /teams/{id}/players will have its own ID (a UUID) and live as a row in its own database table. This means that getting this player will have 2 alternative URIs that contains the necessary information for GETing this resource back:

Slight change of framing: two alternative resources with identifiers that contain the necessary information for GETing this information back.

There's nothing wrong with having the same information available in multiple resources (see Fielding, 2000). There are tradeoffs, of course - for example, general purpose caches are not going to know that the two resources are "really" the same thing. But REST and HTTP both give you the freedom to choose the resource model with the best tradeoffs for your context.

On the other hand, keep in mind that this exchange is perfectly fine:

POST /teams/{id}/players HTTP/1.1

...

HTTP/1.1 200 OK
Location: /players/4781156a-c31f-4ed9-a099-c715734d8281

...

There's no HTTP/REST constraint that requires new resources be created "under" the collection resource. That's just a convention, and HTTP will continue to work just fine if you decide that convention isn't suitable.

REST API redundant path parameters

1 Answers1