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?