How to handle many-to-many relationships with multiple incompatible relationship types in RESTful API?


Note this question is about when there are multiple relationship types. This is not the same as this question, where there is only a single member relationship.

Say we have persons and organizations. There are two types of relationships between them. One is employment and the other is customer.

I’d like to be able to get the persons associated with an organization based on either employment or customer, as well as the inverse, getting the organizations associated with a person based on either employment or customer.

Usually when I have relationships like this id just go with:

/persons/<person_id>/organization /organizations/<organization_id>/person 

Now, how should I represent this when the type of relationship is ambiguous, in my example it could be either employment or customer. Here are some alternatives I’ve come up with for accessing all persons who are customers of an organization:

/customers/organizations/<organization_id>/persons /organizations/<organization_id>/customers/persons /organizations/<organization_id>/persons?only_customers=true /organizations/<organization_id>/persons?relationship=customer 

Under the hood these would be modeled as four DB tables:

person <- customer -> organization person <- employment -> organization 

Are there any other ways of doing this? Which would be the canonical way? I’m not very keen on creating new object types. It might be obvious that person could be replaced with employee, or something like that, but that would have huge implications for other parts of the API design and client implementation, thus is not on the table.