Non-standard methods in the path

Overview

In addition to standard HTTP methods, fs/targets sections support non-standard ones: METADATA, CLEAR, DOWNLOADZIP, UPLOADZIP. The set of methods available in a section comes in the methods field of the section description.

A non-standard method can be invoked in two equivalent ways:

  • by the method itself — METADATA /path;

  • by POST on a path with the !<method> suffix — POST /path!metadata.

The second form is suitable where a client or intermediate node does not pass non-standard methods. It works at any nesting depth, for files and for directories.

Two invocation forms

Both requests below return the same response.

Invocation by the METADATA method
METADATA /rest/v1/fs/targets/files/certificates/x.local.pem HTTP/1.1
Invocation by POST with a suffix
POST /rest/v1/fs/targets/files/certificates/x.local.pem!metadata HTTP/1.1
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}

More about the method: Metadata (METADATA).

How the suffix is separated

The suffix is separated at the last exclamation mark in the last path part.

The part after it is considered a method only if it matches a method possible on this route. Everything else is part of the file or directory name.

Last path part How it is interpreted

notes!draft.txt

File notes!draft.txt: draft.txt is not a method.

notes!draft.txt!metadata

METADATA method for file notes!draft.txt.

tail!

File tail!: there is nothing after the exclamation mark.

report!metadata

METADATA method for file report.

File and directory names with an exclamation mark

The suffix separation rule implies what an administrator needs to know.

  • Names containing ! are allowed. notes!draft.txt is an ordinary file, downloaded and deleted like any other.

  • A name ending with ! is safe. For example, tail!.

  • A name whose part after the last ! matches a section method is not allowed — for example, report!metadata or x!delete. Such a file would be unreachable via the API: any access to it would be interpreted as a method call for another file.

    • If such a name is passed in an upload request body, the request is rejected with code 409.

    • In the request address such a suffix is interpreted as a method call, so a file with such a name is also not created by PUT.

Example of refusal when uploading a file with a disallowed name
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8

{
  "error_message" : "Name 'report!metadata' is not allowed: the part after '!' ('METADATA') is a reserved verb on this section, so the file would be unreachable. Rename it without that '!<verb>' suffix.",
  "error_code" : 1406
}

Archive entries

When unpacking an archive into a tree section, the archive structure is preserved: the entry sub/report.pdf goes into the sub subdirectory. Therefore the rule applies to every segment of the entry path, not only to the file name.

  • The file sub/report!metadata is not allowed: the last segment ends with !metadata.

  • The directory sub!clear/ is equally not allowed: the directory itself would be unreachable because access to sub!clear/ would be interpreted as a CLEAR method call for directory sub.

  • The entry notes!draft/report.pdf is allowed: draft is not a method.

An archive with a disallowed entry is rejected entirely with code 422, as is an archive with other disallowed entries: not a single file from it reaches the disk. The list of disallowed entries — Archive content requirements.