How best to design a RESTful API for initiating an action

I'm building a RESTful web service that has the usual flavor of CRUD operations for a set of data types. The HTTP verb mappings for these APIs are obvious.

The interesting part comes in where the client can request that a long-running (i.e., hours) operation ag开发者_运维技巧ainst one of the data objects be initialized; the status of the operation is reported by querying the data type itself.

For example, assume an object with the following characteristics:

SomeDataType
{
    Name: "Some name",
    CurrentOperation: "LongOperationA",
    CurrentOperationPercent: 0.75,
    CurrentOperationEtaSeconds: 3600
}

My question, then, is what the best RESTful approach should be for starting LongOperationA?

The most obvious approach would seem to be making the operation itself the identifier, perhaps something along the lines of POST https://my-web-service.com/api/StartLongOperationA?DataID=xxxx, but that seems a bit clunky, even if I don't specify the data identifier as a query parameter.

It's also pretty trivial to implement this as an idempotent action, so using POST seems like a waste; on the other hand, PUT is awkward, since no data is actually being written to the service.

Has anybody else faced this type of scenario in their services? What have you done to expose an API for initializing actions that honors RESTful principals?

TIA,

-Mark

You could do,

POST /LongRunningOperations?DataId=xxxx

to create a new LongRunningOperation. The URI of the long running operation would be returned in the Location header along with a 201 status code.

Or if you want to keep the long running operations associated to the DataId you could do

POST /Data/xxx/LongRunningOperations

Both these options will give you the opportunity to inquire if there are long running operations still executing. If you need information after the operation has completed you can create things like

GET /CompletedLongRunningOperations
GET /Data/xxx/CompletedLongRunningOperations
GET /Data/xxx/LastCompletedLongRunningOperation