Rest – Designing a REST API with resource relationships

apiapi-designrestsingle-responsibilityweb-api

I'm working to design a REST API to be consumed by a React SPA.

The client-side of the SPA queries data about a relationship between two entities: Team and Player where Teams have many Players and Players can only belong to one Team.

I want to query all the Teams and then get all the Players for each team (which you could imagine would be a fairly typical use-case for these resources in a SPA.)

I can see 3 main approaches:

Expand the /teams endpoint to have some param ?expand=player or something similar that includes a player array for each team. The data comes back nice to be consumed by the react application but now the REST API endpoint is becoming more complex and less compliant to the single-responsibility principle.
Query /teams to get the IDs of all teams and then query each team /team/:id/players. But this will increase the # of requests to the backend, although it will separate responsibilities nicer and make things more explicit.
Query /teams to get the IDs of all teams and then query /players/:ids where :ids is the IDs of all the teams. This is also quite explicit but could result in a huge URL and isn't a nice and tidy.

What approach is generally regarded as the best? Of course all of them have trade-offs, but perhaps I am overlooking some trade-offs?

Best Answer

I want to query all the Teams and then get all the Players for each team

How would you do it as a web site?

If you weren't trying to create a "REST API", you would probably just create a single html page that would have all the data you want; one fetch from the client, and tada, you are done.

If there was a lot of data, then you might deliver it as multiple pages, linked together.

But either way, it would just be a big block of HTML, that clients could pull down by getting the link.

Does the spelling of the link matter? Not to the client, they are just fetching it. The server needs to be able to match the correct HTML to the link, but the server can do that any way it likes.

So if you want to put that page in your /teams hierarchy, or in your /players hierarchy, or in a completely separate /league, /reports or /views hierarchy, those are all perfectly fine choices.

The fact that the representation you are using is a JSON document, rather than HTML, or XML, or whatever, doesn't change that.

Part of the point of REST is that its not important that the client be able to disassemble your URI and from it deduce your database schema.

What the server is actually doing to find the correct representation is an implementation detail that we conceal behind the uniform interface.

Related Solutions

REST API, nested routes without providing identifiers at every nested level

No. REST doesn't care about how your organize your resources, only that individual resources are identified by URLs and that resources are discoverable from other resources. If api/competitions/{id}/teams/players makes sense for your application then use it, as long as users can find a link to it.
Roy Fielding's dissertation on Representational State Transfer, specifically sections 5.2.1.1 Resources and Resource Identifiers and 6.2 REST Applied to URI. Also look into HATEOAS (Hypertext as the Engine of Application State).
Yes, if it is both understood by and convenient for users of your application.

REST is a high-level architectural concept. It's not concerned with how you nest your identifiers. That's up to you and your application requirements. Do what makes sense and be obvious about it.

Rest – How to represent object references in JSON

For inspiration, you may want to look into the way some of the json based api's (ex: json api, HAL) handle embedding.

One simple answer is to track your data in a key value store. For example

{ "/players/0" : {...}
, "/players/1" : {...}
, "/players/2" : {...}
, "/players/3" : {...}
, "/teams/0" : {...}
, "/teams/1" : {...}
}

And then you describe the players assigned to your team using local references

, "/teams/0" :
    { refs : 
        [ "/players/0"
        , "/players/1"
        ]
    }

As it happens, this scheme covers the case where you have identifiers too. Or where you only have some identifiers

, "/teams/0" :
    { refs : 
        [ "/players/0"
        , "/players/2ad8cabe-2f93-11e6-ac61-9e71128cae77"
        ]
    }

There are fancier versions of this idea (see the links).

That said, I've been down this road myself, and I really tied myself in knots until I concluded: if what you really have is a list of names, rather than a list of players, admit that to yourself, code it that way, and deal with it. It's the more honest way of representing what's going on in the domain at that point in time.

In which case, the payload of your message should look very close to:

{ "Team 1" : 
  [ "Player 1"
  , "Player 2"
  ]
, "Team 2" :
  [ "Player 3"
  , "Player 4"
  ]
}

If that makes you twitchy, remember: this isn't a description of your domain objects; it's a message. The changes it makes to your domain are a side effect. Jim Webber covers this in the introduction to this talk.

Best Answer

Related Solutions

REST API, nested routes without providing identifiers at every nested level

Rest – How to represent object references in JSON

Related Topic