Handling actions in REST web services

Question

I have a web applications where the user can upload samples that can be processed by the backend. Each sample can have one or more files of different types. Once the information about the sample is uploaded the user can request the sample to be analysed either immediately or later (the analysis can take hours in some case). The backend is based on REST services.

How do I tell the backend to start the analysis? One of the REST principle that the URLs should be based on noun.

So I cannot use

/startAnalysis?sampleId=55&startTime=now

What about cancelling the analysis?

/cancelAnalysis?sampleId=57

Answer 1

The Theory:

Actually you are "allowed" to have API calls that send a response that is not a resource, they are called Actions and when dealing with REST Actions you have to use verbs and not nouns.

For example, a REST API to convert 100 euros to Chinese Yen:

`/convert?from=EUR&to=CNY&amount=100`

Thus your REST actions startAnalysis and cancelAnalysis are valid.

I recommend you to read Web API Design (free eBook) by apigee which is a lovely short introduction to REST API design. It also covers REST Actions.

The Practice:

You can also imagine that the 'start of the analysis' is part of the state of your Analysis resource. And instead of using actions you can use PATCH or PUT to update the state of your Analysis resource.

And a more elaborated solution could be :

1. Have a Sample resource: /sample
2. Have a Analysis resource : /analysis
3. After creating a Sample resource either with POST or PUT, you can create by POST an Analysis resource over the created Sample resource : /sample/1234/analysis
4. In order to start the sample analysis (you can even post information about when to start the analysis).
5. If you want to cancel the sample analysis, you can then DELETE the previously created Analysis resource : /sample/1234/analysis/abcde