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

See also: