We are using the JSON-API standard to develop our API and we have come accross a problem that has no obvious solution following the standard as it seems.
Usecase is the following:
There is an API endpoint that allows you to subscribe to mailinglists. One possible flow is that the user is added with as PENDING which means that the user will receive and opt-in email for confirmation.
If this is the case we want to give back a message to the frontend that can be displayed to the user, urging him to click on the link.
From my standpoint this is not really an error state, more of a follow up meta information. So this means it is not conceptually logical to put it in the error messages. Also if we do put it in the error messages the frontend has to differentiate it from 'the real errors' somehow (statuscodes have such a low resolution that collisions seem inevitable).
However we do not return a resource so we cannot add it as meta information to the resource. So right now I have no idea where to put this information.
One possible solution would be to define some kind of 'Response' resource and put it in there but that just seems like a can of worms.
Any ideas? Input would be greatly valued
If the result of the call is that the user is added to the mailing list, return a 200 OK. If the result of the call is that the user has to opt-in via email, return a 202 Accepted. Return a response object with the 202 containing the relevant information.
From the spec:
The 202 (Accepted) status code indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility in HTTP for re-sending a status code from an asynchronous operation.
The 202 response is intentionally noncommittal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.