REST API: How to deal with processing logic

Question

I read (among others) the following blog about API design: https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling. It helped me to better understand a lot of aspects, but I have one question remaining:

How do I deal with functionality that processes some data and gives a response directly. Think, verbs like translate, calculate or enrich. Which noun should they have and should they be called by GET, PUT or POST?

P.S. If it should be GET, how to deal with the maximum length of a GET request

Answer 1

Well, I can tell you that I know about this.

GET           // Returns, JUST return  
DELETE        // Delete 
POST          // Send information that will be processed on server
PUT           // Update a information 

This schema is for laravel framework. Will be most interesting that you read the link in ref

Ref: https://rafaell-lycan.com/2015/construindo-restful-api-laravel-parte-1/

Answer 2

You should start with the following process:

1. Identify the resources (nouns) in your system.
2. They should all respond to GET.

Let's take your translation example. You could decide that every word in the source language is a resource. This would give:

http://example.com/translations/en-fr/hello

Which might return:

Content-Type: text/plain
Content-Language: fr

bonjour

If your processes are long-running, you should create a request queue that clients can POST to, and provide them with another (new) resource that they can query to see if the process has completed.

Answer 3

This is really a discussion about naming more so than functionality. Its very much possible to have processed logic in your API, you just need to be careful about naming it.

Imaginary API time. Its got this resource: /v1/probe/{ID} and it responds to GET, POST, and DELETE.

Let's say we want to launch our probes out, and then want the probe to give us back the calculated flux variation of something its observing (totally made up thing). While it isn't a real thing, let's say that this has to be calculated on the fly. One of my intrepid teammates decides to plunk the calculation at GET /v1/1324/calculateflux.

If we're following real REST-ful practices... Oops. Suddenly we're not dealing with a noun, are we? If we have GET /v1/probe/1324/calculateflux we've broken RESTful practices because we're now asking for a verb - calculateflux.

So, how do we deal with this?

You'll want to reconsider the name calculateflux. That's no good - it doesn't name a resource on the probe. **In this case, /v1/probe/1324/fluxvalue is a better name, and /v1/probe/1324/flux works too.

Why?

RESTFUL APIs almost exclusively use nouns in their URIs - remember that each URI needs to describe a specific thing you can GET POST PUT or DELETE or whatever. That means that any time there is a processed value we should give the resource the name of the processed (or calculated) value. This way, we remain RESTful by adhering to the always-current data (We can re-calculate the Flux value any time) and we haven't changed the state of the probe (we didn't save any values using GET).