Multiple application/json for same http POST request

Question

I am designing a REST API for incident reporting. There are are three state for one incident. ie investigation,resolved and postmortem.

I use uri for incident resource as

 /incident/{incident_id}/{status}

Here incident_id denotes unique id of an incident and status denotes state of an incident.

User can create new incident(this is in investigation state) using

 POST - /incident

Say uri after creating incident is

/incident/123

The applicatoin/json which is needed to be send with POST request to create resolved state and postmortem state of an incident are different.

Then there are two application/json for same uri.

I don't need change uri to

 POST -/incident/investigation/{incident_id}
 POST -/incident/resolved/{incident_id}
 POST -/incident/postmortem/{incident_id}

How to fix this problem?

Answer 1

The application/json which is needed to be send with POST request to create resolved state and postmortem state of an incident are different.

So there are two common answers here.

One is that the POST endpoint for the resource inspects the JSON object to figure out which request was made by the client, and then does the right thing.

The more mature version of this same idea is to use a different Content-Type to distinguish the json documents. That is to say, if you define an application/vnd.resolved+json schema and an application/vnd.postmortem+json schema, then the client reports in the http headers which form of message it is sending to you.

POST /incident/12345
Content-Type: application/vnd.resolved+json

{ "resolved" : { ... } }


POST /indicdent/12345
Content-Type: application/vnd.postmortem+json

{ "post-mortem" : { ... } }

RFC 6838 describes the protocols for registering new media type formats, as well as reserving several namespaces for unregistered types.