How would you design HTTP endpoints for a many-to-many relationship — say users belonging to teams — where the membership itself carries data such as a role and a joined-at timestamp?

## The modelling decision A many-to-many relationship has no natural owner: a user is not inside a team and a team is not inside a user. So the first question is whether the *relationship itself* has state. - **No state** — the link is just "these two are connected". Model it as an association endpoint under one side. - **State** — role, joined date, inviter, expiry, status — the relationship is an entity in its own right (a "membership", "enrollment", "assignment"). Give it a resource with its own identifier. Getting this wrong is the usual failure: teams start with a plain member list, then someone needs roles, and the API grows `POST /teams/7/members/u1/role` and other one-off endpoints instead of admitting there is a Membership. ## Design A: the relationship as a resource ``` POST /teams/7/memberships -> 201, Location: /memberships/m9 GET /memberships/m9 PATCH /memberships/m9 DELETE /memberships/m9 GET /teams/7/memberships?role=admin&limit=50 GET /users/u1/memberships GET /memberships?teamId=7&userId=u1 ``` Why this shape: - **Symmetry.** Both parents can list their side without either owning the relationship. - **A single canonical URI** for the membership means updates, ETags, concurrency control and audit all have one address. Trying to `PATCH /teams/7/members/u1` instead means the resource's identity is a composite key spread across the path, which is workable but awkward once you need optimistic concurrency or references from other resources (an audit log entry pointing at "the membership"). - **Room to grow.** Adding `status: invited|active|suspended` is a field, not a new endpoint. - **Uniqueness** is a server-side constraint: creating a second membership for the same (team, user) should return `409 Conflict` — that is the honest status for a request that violates the current state of the resource — with a body pointing at the existing membership. Creation can be posted to either parent's collection; pick one (usually the side that owns permissions — the team) and document it, so there is one code path enforcing invariants. ## Design B: the link-only association endpoint When the relationship carries nothing: ``` PUT /teams/7/members/u1 -> 204 No Content DELETE /teams/7/members/u1 -> 204 No Content GET /teams/7/members ``` `PUT` on the full membership URI is the right verb: the request expresses a desired end state ("u1 is a member"), so repeating it is a no-op and retries after a network failure are safe. `DELETE` is likewise naturally idempotent — deleting a non-member can return `204` or `404`; `204` is friendlier for retries, just be consistent. Some APIs also offer bulk forms (`PUT /teams/7/members` with the full set, or `POST /teams/7/members:add` style batch operations); a full-set `PUT` is dangerous under concurrency because it silently overwrites additions made by others between read and write, so require a conditional request (`If-Match` on the collection's ETag) if you offer it. ## Cross-cutting concerns **Authorization.** Membership endpoints are a classic privilege-escalation surface. Creating a membership with `role: admin` must be checked against the caller's rights *on the team*, not merely their ability to read the user. Deleting your own membership (leaving) and deleting someone else's (removing) are often different permissions on the same endpoint. **Enumeration.** `GET /users/u1/memberships` reveals which teams a user belongs to. Scope it: a caller should generally only see memberships for teams they can see, which means the listing is filtered by the caller's visibility, not just by the path. **Pagination and filtering** belong on the membership collections like any other collection — team member lists get large. **Representation.** Return the membership with links or ids to both sides, and support expanding the user or team inline for the common list view, so a member list does not force one request per member. **Deletion semantics.** `DELETE /memberships/m9` removes the relationship, never the user or the team. Make that explicit in docs, because it is a question interviewers ask and an assumption that has caused real incidents.