CODEWITHSUNDEEP
web-servicesrestarchitecture
user2151982
user2151982

Reputation: 61

Handling actions in REST web services

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

Upvotes: 4

Views: 2709

Answers (2)

fsenart
fsenart

Reputation: 5891

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

Upvotes: 7

Max DeLiso
Max DeLiso

Reputation: 1244

I think the REST principle you mention is actually only used for GET uris. GET uris should be nouns because you are simply requesting a resource, maybe with parameters. for a PUT or POST uri, they should be verbs instead, because they are causing a change of state.

Upvotes: 0

Related Questions