Section descriptions (targets)

Overview

Returns a machine-readable description of the fs/targets sections available to the account in the current domain: their design, supported operation set, and limitations.

The endpoint is intended for applications working with file sections. It eliminates the need to keep a private copy of section information in the application: the section composition differs by domains and roles and expands as the platform evolves, while the description always matches the current server state.

Note the difference between the two addresses:

Endpoint What it returns

/rest/v1/fs/targets/

List of section names. The general region listing mechanism, see Targets.

/rest/v1/fs/targets

Section descriptions. This article.

The difference is the trailing slash.

Requests

HTTP verb Endpoint Description

GET

/rest/v1/fs/targets

Getting section descriptions


Getting section descriptions

Specifics

  • The list composition is filtered by the same rules as the name list: role policy and domain type are taken into account.

  • Some sections do not appear in the description while remaining in the name list and preserving access via their routes: websocktemp is internal and bound to the session’s WebSocket connection; alertcall is not used by the notification service.

  • An application that did not receive a description (404 or an array of strings from an older server version) must continue working on its own section information.

Request

Example request
GET /rest/v1/fs/targets HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "schema" : 1,
  "version" : "1.11.0",
  "domain" : "example.local",
  "domain_type" : "master",
  "limits" : {
    "max_file_size" : 536870912,
    "recursive_delete" : { "files" : 10000, "bytes" : 10737418240 }
  },
  "groups" : [
    { "id" : "sounds", "title" : "Sounds" },
    { "id" : "certs", "title" : "Certificates" },
    { "id" : "domain_files", "title" : "Domain files" },
    { "id" : "publish", "title" : "Publishing" },
    { "id" : "provisioning", "title" : "Auto-provisioning" },
    { "id" : "storage", "title" : "Storage roots" },
    { "id" : "system", "title" : "System" }
  ],
  "targets" : [
    {
      "name" : "cacerts",
      "url" : "/rest/v1/fs/targets/cacerts",
      "title" : "Root certificates",
      "summary" : "Additional root certificates used to verify external services",
      "structure" : "tree",
      "params" : [],
      "methods" : {
        "collection" : [ "GET", "POST", "METADATA", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ],
        "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ],
        "directory" : [ "GET", "METADATA", "PUT", "DELETE", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ]
      },
      "writable" : true,
      "max_file_size" : 536870912,
      "doc" : "/docs/era/latest/api/rest/v1/fs/targets/cacerts.html",
      "group" : null,
      "storage" : null,
      "macro" : null,
      "public_url" : null,
      "caution" : "normal",
      "actions" : [
        { "id" : "reload",
          "method" : "RELOAD",
          "url" : "/rest/v1/master/logicalroles/all/cacerts",
          "label_key" : "actions.cacerts.reload" }
      ]
    },
    {
      "name" : "syncroot",
      "root_suffix" : "common",
      "url" : "/rest/v1/fs/targets/syncroot/common",
      "title" : "Synchronization root",
      "structure" : "tree",
      "params" : [],
      "methods" : { "collection" : [ "GET", "POST", "METADATA", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ],
                    "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ],
                    "directory" : [ "GET", "METADATA", "PUT", "DELETE", "CLEAR", "DOWNLOADZIP", "UPLOADZIP" ] },
      "writable" : true,
      "doc" : "/docs/era/latest/api/rest/v1/fs/targets/syncroot_common.html"
    },
    {
      "name" : "cpd_templates",
      "url" : "/rest/v1/fs/targets/cpd_templates/{type}",
      "title" : "CPD templates",
      "structure" : "flat",
      "params" : [
        { "name" : "type", "in" : "path", "required" : true, "values" : [ "ivr", "queue" ] }
      ],
      "methods" : { "collection" : [ "GET", "POST", "METADATA" ],
                    "item" : [ "GET", "HEAD", "POST", "PUT", "DELETE", "METADATA" ] },
      "writable" : true
    }
  ]
}

Description composition

Common fields

Field Type Description

schema

int

Description format version. An application encountering an unfamiliar value must ignore the entire description and work on its own information.

version

str

Platform version.

domain, domain_type

str

Current domain and its type (master or worker). The section composition and write permission depend on them.

limits.max_file_size

int

Maximum request body size in bytes.

limits.recursive_delete

object

Recursive operation boundaries: file count and total volume. See Directory operations.

groups

array<object>

Group catalog for displaying sections in applications: id and an English name.

A section references a group via the group field. A section without a group returns null — the application classifies such sections as "other" itself; there is no separate group for them in the catalog.

targets

array<object>

Section descriptions.

Section fields

Field Type Description

name

str

Section name. Matches the name from the list /rest/v1/fs/targets/, which is how the description is matched to the list.

root_suffix

str

Root tail for composite sections. Present for syncroot (common), globalshare, and siteshare (public). The section name remains the first path segment.

url

str

Full collection path, including the root suffix.

title, summary

str

Section name and brief purpose in English. Applications display them as is and do not translate them.

structure

str

tree — the section supports nested directories of arbitrary depth; flat — only single-level files. The availability of directory operations and archives depends on this.

params

array<object>

Path parameters. For cpd_templates this is type; allowed values come in the values field.

methods

object

Actually supported methods, separately for the collection (collection), file (item), and directory (directory).

The set depends on the section and the current domain, see How method sets are formed. The directory key is present only for sections with tree structure. Collection DELETE is not supported by any section — the section root cannot be deleted, only cleared.

writable

bool

Whether writing is allowed in the current domain. The product section is read-only in a working domain.

max_file_size

int

File size limit for this section.

doc

str

Address of the section help article on the same server.

storage

str

Directory storage category.

macro

str

Prefix for accessing the section from scripts.

public_url

str

Public link template for sections with published content.

actions

array<object>

Actions an administrator can perform on the section. Each element: id, method, url, and label_key — the key of the button label that the application localizes.

For example, cacerts has a reload of the certificate list on nodes after the composition changes.

The server never invokes these actions itself. The field describes what the application offers the user to click: when uploading several files, the action is performed once, not after each.

Sections without actions have an empty array, not null.

caution

str

Danger level of operations on the section: normal or high.

high means the section contents affect the operation of the entire installation or all domain data, and the application must require additional confirmation before deletion and clearing. The flag does not change server behavior.

How method sets are formed

The methods field describes what the server will accept in the current domain for this section, not what the handler declares in general. The base set is narrowed by three independent rules.

The item route is absent in this domain. Then item is an empty array. This is how the product section is designed: in a working domain only the archive list is available, to choose a version when installing the product layer, and an individual file cannot be accessed. An empty item means "file operations are unavailable here", not "the section is empty".

Writing in the section is unavailable in this domain. Then write methods are excluded from all sets — POST, PUT, DELETE, CLEAR, UPLOADZIP. Read methods remain: a directory can be downloaded as an archive from a read-only section. The writable value is then false; it answers the same question briefly, while methods answers precisely.

The section is single-level. Then the directory key is absent from methods altogether. This differs from an empty array: an empty set would mean directories exist here but no operations are provided for them, whereas a single-level section never has subdirectories.

The rules are independent and can apply simultaneously. For product in a working domain, all three apply at once.

The application does not need to compare methods with structure or writable: the set already accounts for both.

The storage, macro, public_url, and group fields may be null: information is set per section and not all are filled. The application must work correctly when a value is absent — not show the corresponding action rather than substitute its own.

See also