423 Locked
The 423 Locked status-code does not appear in the base
HTTP specification, but is part of WebDAV specification, which is an
extension to HTTP.
A major goal of WebDAV was to provide a ‘filesystem over the web’. One of its core features is for users to ‘lock’ specific files and directories to prevent others from editing them.
A user can lock a resource by issuing a http LOCK method and later on
unlock the resource by using the UNLOCK HTTP method.
Both ‘shared locks’ and ‘exclusive locks’ are supported.
Example
Locking a resource
LOCK /article/5 HTTP/1.1
Content-Type: application/xml
<?xml version="1.0"?>
<d:lockinfo xmlns:d='DAV:'>
<d:lockscope><d:exclusive/></d:lockscope>
<d:locktype><d:write/></d:locktype>
<d:owner>Evert</d:owner>
</d:lockinfo>
A successful response to this includes a Lock-Token header.
HTTP/1.1 200 OK
Content-Type: application/xml
Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
<?xml version="1.0"?>
...
If a user tries to make a change to a locked resource, they will get an error:
PUT /article/5 HTTP/1.1
Content-Type: text/plain
New content
HTTP/1.1 423 Locked
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8" ?>
<d:error xmlns:d="DAV:">
<d:lock-token-submitted>
<d:href>/article/5</d:href>
</d:lock-token-submitted>
</d:error>
Unless, they also include the lock-token in the If header:
PUT /article/5 HTTP/1.1
Content-Type: text/plain
If: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
New content
HTTP/1.1 204 No Content
Usage on the web
I haven’t seen a lot of usage of LOCK, UNLOCK and the 423 code outside
of WebDAV. However, I don’t see strong reasons against their usage.
A big part that the lock functionality of WebDAV hopes to solve, is avoiding problems with multiple users making updates on (groups of-) resources at the same time.
If you also have this issue, bear in mind that there is a more popular feature
in HTTP to deal with this: Etags and the If-Match / If-None-Match headers.
These headers tend to work a bit better, especially if they are required because they give a strong indicator to an end-user: you are about to overwrite someone’s changes. If ETags solve your concurrency or ‘lost update’ use-case, it’s likely better.
However, one thing LOCK does is that it allows a user to reserve a resource
in advance for editing. It basically can give an indication to other users:
“someone is currently working on this document”.
Is that problem solvable without resorting to WebDAV http methods? Probably!
Your REST resources could for example simply expose a lockedBy JSON property.
When set, it could prevent only that user to make changes.
References
- RFC4918, Section 11.3 - 423 Locked
- RFC4918, Section 9.10 - LOCK method
- RFC4918, Section 9.11 - UNLOCK method
See also: