What is the "Restful" way to command a server?

user_13429959 0
Viewed 392

I have a REST endpoint to create an application configuration as such

POST /applications

With a body

{
    "appName" : "my-new-app"
}

I returns a newly created application configuration:

{
  "appName": "my-new-app",
  "appId": "2ed17ff700664dad9bb32e400d39dc68",
  "apiKey": "$2a$10$XVDH9F3Ix4lx2LdxeJ4ZOe7H.bw/Me5qAmaIGF.95lUgkerfTG7NW",
  "masterKey": "$2a$10$XVDH9F3Ix4lx2LdxeJ4ZOeSZLR1hVSXk2We/DqQahyOFFY6nOfbHS",
  "dateCreated": "2021-03-28T11:00:07.340+00:00",
  "dateUpdated": "2021-03-28T11:00:07.340+00:00"
}

Note: The keys are auto-generated in the server and not passed from the client.

My question here is, what's the RESTful way to command the server to reset the keys for example:

PUT /applications/my-new-app/update_keys is not noun-based and thus, not restful, also passing a command as query parameter does not also seem to be restful since this is not a GET method rather it's a PUT (update) method.

api-design hateoas rest
2 Answers

Here's one way to send a command that is as much as possible RESTful:

Endpoint:

POST /application/:appName/actions

Example Payload:

{
    "actions" : [
      {
        "action" : "name_of_command",
        "arguments" : {
          "arg1" : "param1"
        }
      },
      {
        "action" : "reset_keys",
        "arguments" : {
        }
      }
    ]
}

Actions would be nouns that are part of the endpoint, and the server will process actions that are submitted (or posted) within the endpoint. And an array of actions would be best suited to allow multiple actions to be sent. And each action having arguments would also be desirable for future actions that would need arguments.

user_7853490

what's the RESTful way to command the server to reset the keys for example:

How would you do it with a web site?

You would be looking at some web page like /www/applications/my-new-app; within the data or the metadata you would find a link. Following that link would bring you to a form; the form would have input controls describing what fields you need to provide to send the message, in addition to any "hidden" inputs. When you click the submit button, your user agent would collect your inputs, construct from them the appropriate message body, then use the form metadata to determine what request method and uri to use.

The client never has to guess what URI to use, because the server is providing links to guide the way.

Hypertext is at the heart of the uniform interface

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

Because the server is providing the URI for each of the links, you've got some freedom ot choose which resource "handles" which message.

One interesting way to resolve this to look at HTTP's rules for cache invalidation. The short version is that successful unsafe requests (PATCH/POST/PUT) invalidate the representations of the target-uri.

In other words, we take advantage of cache-invalidation by sending the command to the resource that we are trying to change.

So, assuming that retrieving the representation of the app occurred via a request like:

GET /applications/my-new-app HTTP/x.y

Then we would ask the server to change that resource by sending a request with that same target-uri. Something analogous to:

POST /applications/my-new-app HTTP/x.y
Content-Type: text/plain

Please rotate the keys

Form submissions on the web are usually a representation of key/value pairs, so a more likely spelling would be:

POST /applications/my-new-app HTTP/x.y
Content-Type: applications/x-www-form-urlencoded

action=Please%20rotate%20the%20keys

Your form that describes this request my have an "action" input control, that accepts text from the client, or more likely in this case action would be a hidden control with a pre-defined value.

Note: if we have multiple actions that should invalidate the /applications/my-new-app representations, we would probably use POST for all of them, and resolve the ambiguity at the server based on the request-body (if our routing framework gives us the degree of control we need, we can use that - but more common would be to have a single POST handler for each Content-Type, and parse the request body "by hand".

POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding 2009

PUT /applications/my-new-app/update_keys is not noun-based and thus, not restful,

That's not true: REST doesn't care what spelling conventions you use for your resource identifiers. For example

These all work fine, just like every other resource on the web.

You absolutely can design your resource model so that editing the update_keys document also modifies the my-new-app document.

The potential difficulty is that general purpose components are not going to know what is going on. HTTP PUT means "update the representation of the target resource", and every general purpose component knows that; the origin server is allowed to modify other resources as a consequence of the changes to the "update-keys" resource.

But we don't have a great language for communicating the general purpose components all of the side effects that may have happened. Without some special magic, previously cached copies of my-new-app, with the original, unrotated, keys, will be left lying around. So the client may be left with a stale copy of the document that describes the app.

(An example of "some special magic" would be Linked Cache Invalidation, which affords describing caching relationships between resources using web linking. Unforunately, LCI has not been adopted as a standard, and you won't find the described link relations in the IANA registry.)

user_547340
Related