CODEWITHSUNDEEP
rest
dwergkees
dwergkees

Reputation: 734

REST Modeling: How do model an action or act to be performed in REST?

I am creating a REST service that allows users to transform an input to a desired output using a predefined translation from a collection of translations.

For managing the translation definitions it seems natural to a have a translations resource that the user can manipulate, such as:

However, I am not sure how I should model the act of performing/requesting a transformation of an input to an ouput.

My current setup is that I do a POST request to a specific translation with the input as body of that request. The response of the request contains the output of the tranlation:

The POST method seems off for me, as I am not creating a resource in the system, I am merely performing a transformation and am not changing the state of the system. The POST method however, is convenient as it allows me to send a Request Body (which the GET Request is not supposed to do).

So: How can I model this action properly in a REST style

Upvotes: 0

Views: 67

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57397

The POST method seems off for me, as I am not creating a resource in the system

POST is fine for what you are doing. From RFC 7231

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

o Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;

Yes, you'd prefer to have a safe method in the uniform interface that supports the payload you want to share. SEARCH is probably closest of the registered methods, but it's not satisfactory.

How can I model this action properly in a REST style

How would you do it as a web site?

You'd probably have the client start by using some bookmark; the returned representation would have a bunch of links in it, advertising capabilities. The semantics within the representation allow the client to discriminate the different links, and find the one it wants. That link would lead the client to representations of one or more forms, with additional semantic hints that would guide the client through the integration protocol you have designed to support translation. When the data had been collected, the client would submit the form to the the endpoint specified within the form representation, which would direct the request to your translator.

If you do that; but make the semantics within the representations machine readable, you've got yourself a REST api.

Notice: the hard part of REST isn't coming up with a URI, or guessing the right HTTP method to use. The hard part is ensuring that the client implementation and the server implementation are decoupled from each other.

Upvotes: 2

Related Questions