RESTful trigger function

Question

I have java restful service with a functionality that runs on a schedule. I want to implement a way to run that functionality on demand. what would be the proper/most effective way to achieve this?

Answer 1

So I'm hesitant as to what method to use and if there's any other way to achieve this without cheating the REST architecture.

"It is okay to use POST." (Fielding, 2009)

Analog: if you were building a boring website, then you would present the operator with a web form, with a "submit" button that would send a request to the web server. You probably wouldn't want the form submitted preemptively, so you would set the form method to POST so that general purpose components would understand that the semantics of the form are not "safe".

That said, you could instead design the interaction using the metaphor of passing a new document to the server to store, where the storage of that document would trigger the side effects that you want. In other words, instead of a resource to which you post messages, which are then processed using the semantics unique to that resource, you could instead treat the message itself as a resource, and use remote authoring semantics (PUT/DELETE/PATCH) to deliver that information to the server.

Both options are fine, as far as REST is concerned.

That fact that the messages themselves have no explicit "state" really isn't important at all, from a REST perspective.

Answer 2

As REST is basically just a generalization of how we humans use the Web you can simply design the interaction like a human would interact with your service naturally. I.e. you could have a "page" (=resource) that lists all of the registered tasks, i.e. with a short human-readable description of what that task is doing, the scheduled time slot and links for editing or removing the respective task. Internally for each of the listed tasks a cronjob or the like will be created that executes at the specified intervals or if configured as one-time shot task on that particular time and then gets removed from the scheduled tasks.

That list would also provide links for creating new tasks, edit or delete existing ones. An edit would naturally render the properties of the task at hand in a particular form, fill out all of the specified fields in that form and therefore allow a client to change stuff of it and then simply send back the data to the server. Clicking the delete link might bring up a check whether you really want to delete that task. That is basically HATEOAS. You used the given control elements like links, forms and its various fields and buttons, to drive your workflow.

You could either send out HTML as response or map the data of the resource to an other format, i.e. like a popular JSON based payload. That payload should however follow a document type that is able to express links and forms and all of that jazz to clients, plain JSON can't do that. application/hal+json (HAL) adds support for links and embedded content to the mix, application/prs.hal-forms+json (HAL-Forms) extends HAL by adding form support, application/ion+json or application/ion+json;v=2 (Ion) (btw, don't confuse it with Amazon's Ion ^^) is yet a different JSON based syntax which though also support forms. There are actually a couple of these out there. Some of these media types even support profiles where some additional "meaning" could be added, like i.e. in

application/vnd.collection+json;profile=http://example.org/profiles/order http://schema.org/Order

the server states that it returns a representation that the client should interpret as list or collection which contains entries that express orders and follow some common or proprietary order definition. A client not being able to process profiles has to basically ignore them and those capable of processing that additional information might be able to apply a more suitable mapping instead of a generic one.

The goal you want to achieve with REST is to gain freedom to develop the server-side as you see fit and don't have to fear of breaking clients, which sadly happens all to often when clients couple to servers. Instead of clients coupling to a particular API, both client and server use media types as their contracts for exchanging messages. In contrast to traditional RPC systems however you are not limited to one single message format and syntax but can support various different ones, i.e. like the above mentioned HAL, HAL-Forms and Ion. It is therefore just a matter of content type negotiations which style of response the server should generate for the client.

The strong focus on media types guarantees that servers have to express the state of a resource in the capabilities of the media type. It should not generate some markup or syntax that is not defined in the spec as recipients might not know how to process that data. And interoperability is one of the main concerns in REST.

Of course, this requires way more work to get stuff working. I.e. you might need a mapping from that common representation format to your internal model. With a flexible mapping your client i.e. should be able to interact with plenty other services out there without the need for a big change, like it is the case with humans serving the Web. I've even seen attempts to use generative AI to help in those mappings