REST API 强制更新资源

Question

What is a good practice for a rest api to allow a force update. The normal update will return a warning if something is exceeded.

I was thinking:

1. PUT /myresource/{id}?options=FORCE
2. PUT /myresource/{id}, include optional options field in payload.

Any better approach?

Thanks

Answer 1

PUT /myresource/{id}?options=FORCE

This is a bad idea that you can probably make work if you insist upon it.

The core idea of REST is that we have a uniform interface - all resources understand messages the same way. In the case of PUT, that means that we all understand the message as described by RFC 7231

The target-uri of the request indicates which resource a given message applies to. So from the perspective of general purpose components, PUT /myresource/{id}?options=FORCE means "please update the representation of /myresource/{id}?options=FORCE".

Note the deliberate inclusion of the query part, which is part of the identification of the primary resource.

"/myresource/{id}?options=FORCE" is a different resource identifier than "/myresource/{id}", even though the hierarchical parts of the URI are the same.

So from the point of view of a general purpose component (like a browser, or a caching web proxy), your proposed request leaves the cached representations of "/myresource/{id}" unchanged.

You can probably make it work: if you read the cache invalidation specification carefully, you will see that the target-uri is not the only URI that is invalidated by a successful response to an unsafe request; the cache is also expected to invalidate the resources identified by the Location and Content-Location headers.

So a response like:

200 OK
Content-Location: /myresource/{id}

<<updated representation of /myresource/{id}

will invalidate both /myresource/{id}?options=FORCE and /myresource/{id}.

Of course, using the Content-Location header in this way introduces other constraints.

PUT /myresource/{id}, include optional options field in payload.

Better - we're identifying the resource really want to modify (so the caches now understand what is going on). Since you probably don't intend that the optional fields you are using to force the update become part of the server's representation, you need to do a bit of extra fuss in the response to avoid implying that the requested representation was accepted as is.

---

Another option would be to consider using the Authentication header; analogously to how one would use sudo rm -rf to override the default policy. In effect, your implementation logic is expected to check whether the author of the request has been assigned to a role that allows edits beyond those allowed by the default policy.

---

If you aren't satisfied that your needs align well with the existing semantics of the Authentication header, you can instead introduce a new header

New header fields can be defined such that, when they are understood by a recipient, they might override or enhance the interpretation of previously defined header fields, define preconditions on request evaluation, or refine the meaning of responses.

For example, see RFC 8594 .

Hard part here is adoption.

In a situation where you control both the client(s) and the server, adoption is much easier, since you can force the issue.