Bulk credit endpoint spec

[remear]

Not ready for merge

Exemplifies Option 1 for handling bulk credits.

[mjallday]

there should be a response body

[remear]

What would the response body consist of?

[mjallday]

a collection of credits! ;)

[remear]

Then we're expecting the client to wait around while the credits are created, right?

Or should this be a fire-and-forget endpoint and API consumers are responsible for watching for these credits via events?

[mjallday]

in that case it should give a 202 HTTP status code

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

202 Accepted

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 for re-sending a status code from an asynchronous operation such as this.

The 202 response is intentionally non-committal. 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 entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.

[remear]

Bulk crediting via a sweep-type account is the preferred choice. Pull request progress will be tracked in #707