For an application I’ve been working on, we’re building in issue-tracking features, similar to issues in GitHub / GitLab / etc. There’s an issue type, and a change-record type, where the client needs to provide edits to the issue and additional information that will only be part of the change-record.
This suggests that there’s a change-request object type that’s POSTed to the server, but what’s created is a change-record (with side effects on the issue resource, all described in the change-record resource that’s created).
It’s unclear to me whether this is a good way to model this, but it needs to be a single request for sane transaction management.
Is there a better or cleaner way to represent such an interaction with JSON:API?
I don’t see a clean JSON:API-compliant way to do that. A POST to the collection of change-record resources could return either a 201 to the new change-record, or maybe a rendering of the individual change-record, but getting the issue back would be a bit weird.
Retrieving the issue again could provide the entire set of change-record objects via include, though. But the client has to know to do that, which is beyond the JSON:API specification (though reasonable for this specific application).
Were I POSTing to the issue, that would be reasonable. But the change-request includes fields that do not (and should not) exist in the issue, but only in the change-record (in addition to fields that are in the issue).
It the change being made only consists of fields from the issue, a PATCH to the issue works best, and the change-records can be forwarded in included.
My question is really one of whether it makes more sense to define the additional fields for the change-record as write-only fields for the issue, or wire things together some other way. This isn’t an unusual approach, but it’s hard to describe it as particularly compliant with REST models; it steps a little (at least) to the side.
Looking back at this after so long, I think posting to the collection of changes and returning both the change-record and the issue would be entirely reasonable; the change-record would have to have a relationship back to the issue, which is arguably a good idea.
Of course, at the time, I didn’t include such a relationship, and wasn’t thinking about the possibility that the default include could be non-empty.
Maybe I should fix that.
@niltz: Thanks for making me really think it through, even if it took me a long time!
