I’ve returned back to this question while designed Conversations system.
GET /conversations could return different types of conversations. Each conversation type scoped by different scope types.
Candidate has an interview for a Job. It’s JobInterview conversation:
POST /conversations
{
"data": {
"type": "JobInterview",
"relationships": {
"scopes": {
"data": [
{
"type": "Job",
"id": "job-1"
},
{
"type": "Candidate",
"id": "candidate-1"
}
]
}
}
}
}
As you can see both of scopes are located in polymorphic scopes relationship. It works well when you want to add another type of conversation which requires another scope types. For example DisputeNegotiation conversation will require scopes of type Dispute and maybe NegotiationSession if you want to break them down daily.
It’s easy to collect the data because GET /conversations will return all the types of the conversations and you could filter them out. But isn’t that hard for a client to understand what scopes are required for concrete type of conversation? I don’t even know how to describe in documentation and error messages that conversation of type JobInterview requires 2 scopes where first one MUST be Job and the second one MUST be Candidate. And conversation of type DisputeNegotiation requires 2 scopes where first one MUST be Dispute and the second one MUST be NegotiationSession. Moreover there is possibility of conversations with more or less than 2 scopes.
All this things makes me feel wrong. Wouldn’t it be clearer for the client to have this API:
POST /conversations
{
"data": {
"type": "JobInterview",
"relationships": {
"job": {
"data": {
"type": "Job",
"id": "job-1"
}
},
"candidate" {
"data": {
"type": "Candidate",
"id": "candidate-1"
}
}
}
}
}
Then if client want to create DisputeNegotiation he will have another 2 relationships: dispute and session. Then documentation and error messages will be clear and human friendly. But then we are returning to the issue which I described earlier. While getting resources from endpoint GET /conversations each resource type will have different relationships.
After all I’ve thought about resource creation could use concrete relations (eg. job, candidate, dispute and etc) and resource fetching could use concrete or abstract relationship scopes for the filtering purposes. Under the hood all this concrete relations will store as scopes. That will give client an opportunity to chose what way to use. But it’s not obvious behavior that modifying scopes will affect on concrete relationships. Then I suppose it would be better to make scopes relationship read only.
Isn’t it an overkill?
