POST one resource type to create another

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?


Could you return the newly created change-record and updated issue in the response as included data?

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).


Why could you not return the updated issue and created change-record in the included part?

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.