My question is, what would be the RESTful way to expose the “renew” functionality?
How would you do provide this functionality on a website?
You would presumably start by looking at the web page of the entry, via a GET request, that would load the current representation of the page into your local cache.ou
When the server judged that the entry was eligible for renewal, the web page would include some sort of hypermedia affordance for allowing the client to trigger the renew protocol. In this case, you probably don't want that affordance to have safe semantics, so it would be a form using the POST method. When the user submitted the form, the browser would create an HTTP request with the correct meta data and form data copied into the request body as described by the HTML processing rules; the request would be submitted to the URL specified in the form.action by the server.
Does the spelling of the URL matter to the user? Not really, the user just submits the form, the URL is just opaque data. Indirectly, it matters because of the way that cache invalidation semantics are defined -- if we intend that renewing should evict previously cached representations of the web page, then the post request should have the URL of the page itself.
Similarly, the web form doesn't need to be on the page - you could have a link to a form managed elsewhere, using different caching rules.
Do that, in a machine readable way, and you have yourself a REST API.
PUT and PATCH work the same basic way, except that request body is a description of the page itself. Download the HTML, make edits, then either PUT the new document in its entirety or compute a patch document and send that instead.
PUT and PATCH work really well for anemic domains - like document stores; it's more challenging to work with representations directly when you need to reverse engineer the change in order to work out the intent.
