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 |
|---|---|
|
List of section names. The general region listing mechanism, see Targets. |
|
Section descriptions. This article. |
The difference is the trailing slash.
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
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:
websocktempis internal and bound to the session’s WebSocket connection;alertcallis not used by the notification service. -
An application that did not receive a description (
404or an array of strings from an older server version) must continue working on its own section information.
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 |
|---|---|---|
|
|
Description format version. An application encountering an unfamiliar value must ignore the entire description and work on its own information. |
|
|
Platform version. |
|
|
Current domain and its type ( |
|
|
Maximum request body size in bytes. |
|
|
Recursive operation boundaries: file count and total volume. See Directory operations. |
|
|
Group catalog for displaying sections in applications: A section references a group via the |
|
|
Section descriptions. |
Section fields
| Field | Type | Description |
|---|---|---|
|
|
Section name. Matches the name from the list |
|
|
Root tail for composite sections. Present for |
|
|
Full collection path, including the root suffix. |
|
|
Section name and brief purpose in English. Applications display them as is and do not translate them. |
|
|
|
|
|
Path parameters. For |
|
|
Actually supported methods, separately for the collection ( The set depends on the section and the current domain, see How method sets are formed. The |
|
|
Whether writing is allowed in the current domain. The |
|
|
File size limit for this section. |
|
|
Address of the section help article on the same server. |
|
|
Directory storage category. |
|
|
Prefix for accessing the section from scripts. |
|
|
Public link template for sections with published content. |
|
|
Actions an administrator can perform on the section. Each element: For example, 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 |
|
|
Danger level of operations on the section:
|
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
-
Targets — list of sections and articles for each.