Resource URL: /platform/<<version=3>>/protocols/smb/shares

    Overview: This resource applies the standard collection pattern to SMB
              shares.

     Methods: GET, POST, DELETE

********************************************************************************

Method GET: List all shares.

       URL: GET /platform/<<version=3>>/protocols/smb/shares

Query arguments:
            sort=<enum> Where <enum> is one of id, name, path, description.
                        Order results by this field. Default is id.
          zone=<string> Zone which contains this share.
        resume=<string> Continue returning results from previous call using
                        this token (token should come from the previous call,
                        resume cannot be used with other options).
resolve_names=<boolean> If true, resolve group and user names in personas.
        limit=<integer> Return no more than this many results at once (see
                        resume).
           scope=<enum> Where <enum> is one of user, default, effective.  If
                        specified as "effective" or not specified, all fields
                        are returned.  If specified as "user", only fields with
                        non-default values are shown.  If specified as
                        "default", the original values are returned.
             dir=<enum> Where <enum> is one of ASC, DESC.  The direction of the
                        sort.

GET response body schema:
{
  "type": "object", 
  "properties": {
    "total": {
      "type": "integer", 
      "description": "Total number of items available."
    }, 
    "shares": {
      "items": {
        "required": true, 
        "type": "object", 
        "properties": {
          "file_create_mode": {
            "type": "integer", 
            "description": "File create mode bits."
          }, 
          "ntfs_acl_support": {
            "type": "boolean", 
            "description": "Support NTFS ACLs on files and directories."
          }, 
          "file_filtering_enabled": {
            "type": "boolean", 
            "description": "Enables file filtering on this zone."
          }, 
          "directory_create_mask": {
            "type": "integer", 
            "description": "Directory create mask bits."
          }, 
          "inheritable_path_acl": {
            "type": "boolean", 
            "description": "Set the inheritable ACL on the share path."
          }, 
          "ca_write_integrity": {
            "enum": [
              "none", 
              "write-read-coherent", 
              "full"
            ], 
            "type": "string", 
            "description": "Specify the level of write-integrity on continuously available shares."
          }, 
          "file_create_mask": {
            "type": "integer", 
            "description": "File create mask bits."
          }, 
          "path": {
            "required": true, 
            "type": [
              "null", 
              "string"
            ], 
            "description": "Path of share within /ifs."
          }, 
          "access_based_enumeration_root_only": {
            "type": "boolean", 
            "description": "Access-based enumeration on only the root directory of the share."
          }, 
          "allow_variable_expansion": {
            "type": "boolean", 
            "description": "Allow automatic expansion of variables for home directories."
          }, 
          "id": {
            "required": true, 
            "type": [
              "null", 
              "string"
            ], 
            "description": "Share ID."
          }, 
          "hide_dot_files": {
            "type": "boolean", 
            "description": "Hide files and directories that begin with a period '.'."
          }, 
          "create_permissions": {
            "enum": [
              "default acl", 
              "inherit mode bits", 
              "use create mask and mode"
            ], 
            "type": "string", 
            "description": "Create permissions for new files and directories in share."
          }, 
          "strict_locking": {
            "type": "boolean", 
            "description": "Specifies whether byte range locks contend against SMB I/O."
          }, 
          "mangle_map": {
            "items": {
              "type": "string"
            }, 
            "type": "array", 
            "description": "Character mangle map."
          }, 
          "zid": {
            "required": true, 
            "type": "integer", 
            "description": "Numeric ID of the access zone which contains this SMB share"
          }, 
          "file_filter_type": {
            "enum": [
              "deny", 
              "allow"
            ], 
            "type": "string", 
            "description": "Specifies if filter list is for deny or allow. Default is deny."
          }, 
          "file_filter_extensions": {
            "items": {
              "type": "string"
            }, 
            "type": "array", 
            "description": "Specifies the list of file extensions."
          }, 
          "browsable": {
            "type": "boolean", 
            "description": "Share is visible in net view and the browse list."
          }, 
          "description": {
            "type": "string", 
            "description": "Description for this SMB share."
          }, 
          "auto_create_directory": {
            "type": "boolean", 
            "description": "Automatically create home directories."
          }, 
          "continuously_available": {
            "type": "boolean", 
            "description": "Specify if persistent opens are allowed on the share."
          }, 
          "directory_create_mode": {
            "type": "integer", 
            "description": "Directory create mode bits."
          }, 
          "allow_delete_readonly": {
            "type": "boolean", 
            "description": "Allow deletion of read-only files in the share."
          }, 
          "ca_timeout": {
            "minimum": 2, 
            "type": "integer", 
            "description": "Persistent open timeout for the share."
          }, 
          "access_based_enumeration": {
            "type": "boolean", 
            "description": "Only enumerate files and folders the requesting user has access to."
          }, 
          "allow_execute_always": {
            "type": "boolean", 
            "description": "Allows users to execute files they have read rights for."
          }, 
          "csc_policy": {
            "enum": [
              "manual", 
              "documents", 
              "programs", 
              "none"
            ], 
            "type": "string", 
            "description": "Client-side caching policy for the shares."
          }, 
          "run_as_root": {
            "items": {
              "type": "object", 
              "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
              "properties": {
                "type": {
                  "enum": [
                    "user", 
                    "group", 
                    "wellknown"
                  ], 
                  "type": "string", 
                  "description": "Specifies the type of persona, which must be combined with a name."
                }, 
                "id": {
                  "type": "string", 
                  "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
                }, 
                "name": {
                  "type": "string", 
                  "description": "Specifies the persona name, which must be combined with a type."
                }
              }
            }, 
            "type": "array", 
            "description": "Allow account to run as root."
          }, 
          "permissions": {
            "items": {
              "type": "object", 
              "description": "Specifies properties for an Access Control Entry.", 
              "properties": {
                "permission_type": {
                  "enum": [
                    "allow", 
                    "deny"
                  ], 
                  "type": "string", 
                  "description": "Determines whether the permission is allowed or denied.", 
                  "required": true
                }, 
                "trustee": {
                  "required": true, 
                  "type": "object", 
                  "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                  "properties": {
                    "type": {
                      "enum": [
                        "user", 
                        "group", 
                        "wellknown"
                      ], 
                      "type": "string", 
                      "description": "Specifies the type of persona, which must be combined with a name."
                    }, 
                    "id": {
                      "type": "string", 
                      "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
                    }, 
                    "name": {
                      "type": "string", 
                      "description": "Specifies the persona name, which must be combined with a type."
                    }
                  }
                }, 
                "permission": {
                  "enum": [
                    "full", 
                    "change", 
                    "read"
                  ], 
                  "type": "string", 
                  "description": "Specifies the file system rights that are allowed or denied.", 
                  "required": true
                }
              }
            }, 
            "type": "array", 
            "description": "Specifies an ordered list of permission modifications."
          }, 
          "name": {
            "required": true, 
            "type": [
              "null", 
              "string"
            ], 
            "description": "Share name."
          }, 
          "host_acl": {
            "items": {
              "type": "string", 
              "description": "<'allow:'|'deny:'><'ALL'|IP-range|subnet|fqdn>[' EXCEPT '<IP-range|subnet|fqdn>]."
            }, 
            "type": "array", 
            "description": "An ACL expressing which hosts are allowed access. A deny clause must be the final entry."
          }, 
          "change_notify": {
            "enum": [
              "all", 
              "norecurse", 
              "none"
            ], 
            "type": "string", 
            "description": "Level of change notification alerts on the share."
          }, 
          "mangle_byte_start": {
            "type": "integer", 
            "description": "Specifies the wchar_t starting point for automatic byte mangling."
          }, 
          "impersonate_user": {
            "type": "string", 
            "description": "User account to be used as guest account."
          }, 
          "impersonate_guest": {
            "enum": [
              "always", 
              "bad user", 
              "never"
            ], 
            "type": "string", 
            "description": "Specify the condition in which user access is done as the guest account."
          }, 
          "oplocks": {
            "type": "boolean", 
            "description": "Support oplocks."
          }, 
          "strict_flush": {
            "type": "boolean", 
            "description": "Handle SMB flush operations."
          }, 
          "strict_ca_lockout": {
            "type": "boolean", 
            "description": "Specifies if persistent opens would do strict lockout on the share."
          }
        }
      }, 
      "type": "array"
    }, 
    "resume": {
      "type": [
        "string", 
        "null"
      ], 
      "description": "Continue returning results from previous call using this token (token should come from the previous call, resume cannot be used with other options)."
    }
  }
}

********************************************************************************

Method POST: Create a new share.

        URL: POST /platform/<<version=3>>/protocols/smb/shares

Query arguments:
zone=<string> Zone which contains this share.

POST request body schema:
{
  "type": [
    {
      "required": true, 
      "type": "object", 
      "properties": {
        "file_create_mode": {
          "type": "integer", 
          "description": "File create mode bits."
        }, 
        "ntfs_acl_support": {
          "type": "boolean", 
          "description": "Support NTFS ACLs on files and directories."
        }, 
        "file_filtering_enabled": {
          "type": "boolean", 
          "description": "Enables file filtering on this zone."
        }, 
        "directory_create_mask": {
          "type": "integer", 
          "description": "Directory create mask bits."
        }, 
        "inheritable_path_acl": {
          "type": "boolean", 
          "description": "Set the inheritable ACL on the share path."
        }, 
        "ca_write_integrity": {
          "enum": [
            "none", 
            "write-read-coherent", 
            "full"
          ], 
          "type": "string", 
          "description": "Specify the level of write-integrity on continuously available shares."
        }, 
        "file_create_mask": {
          "type": "integer", 
          "description": "File create mask bits."
        }, 
        "path": {
          "required": true, 
          "type": "string", 
          "description": "Path of share within /ifs."
        }, 
        "access_based_enumeration_root_only": {
          "type": "boolean", 
          "description": "Access-based enumeration on only the root directory of the share."
        }, 
        "allow_variable_expansion": {
          "type": "boolean", 
          "description": "Allow automatic expansion of variables for home directories."
        }, 
        "hide_dot_files": {
          "type": "boolean", 
          "description": "Hide files and directories that begin with a period '.'."
        }, 
        "create_permissions": {
          "enum": [
            "default acl", 
            "inherit mode bits", 
            "use create mask and mode"
          ], 
          "type": "string", 
          "description": "Create permissions for new files and directories in share."
        }, 
        "strict_locking": {
          "type": "boolean", 
          "description": "Specifies whether byte range locks contend against SMB I/O."
        }, 
        "zone": {
          "type": "string", 
          "description": "Name of the access zone to which to move this SMB share"
        }, 
        "mangle_map": {
          "items": {
            "type": "string"
          }, 
          "type": "array", 
          "description": "Character mangle map."
        }, 
        "file_filter_type": {
          "enum": [
            "deny", 
            "allow"
          ], 
          "type": "string", 
          "description": "Specifies if filter list is for deny or allow. Default is deny."
        }, 
        "file_filter_extensions": {
          "items": {
            "type": "string"
          }, 
          "type": "array", 
          "description": "Specifies the list of file extensions."
        }, 
        "browsable": {
          "type": "boolean", 
          "description": "Share is visible in net view and the browse list."
        }, 
        "description": {
          "type": "string", 
          "description": "Description for this SMB share."
        }, 
        "auto_create_directory": {
          "type": "boolean", 
          "description": "Automatically create home directories."
        }, 
        "continuously_available": {
          "type": "boolean", 
          "description": "Specify if persistent opens are allowed on the share."
        }, 
        "directory_create_mode": {
          "type": "integer", 
          "description": "Directory create mode bits."
        }, 
        "allow_delete_readonly": {
          "type": "boolean", 
          "description": "Allow deletion of read-only files in the share."
        }, 
        "ca_timeout": {
          "minimum": 2, 
          "type": "integer", 
          "description": "Persistent open timeout for the share."
        }, 
        "access_based_enumeration": {
          "type": "boolean", 
          "description": "Only enumerate files and folders the requesting user has access to."
        }, 
        "allow_execute_always": {
          "type": "boolean", 
          "description": "Allows users to execute files they have read rights for."
        }, 
        "csc_policy": {
          "enum": [
            "manual", 
            "documents", 
            "programs", 
            "none"
          ], 
          "type": "string", 
          "description": "Client-side caching policy for the shares."
        }, 
        "run_as_root": {
          "items": {
            "type": "object", 
            "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
            "properties": {
              "type": {
                "enum": [
                  "user", 
                  "group", 
                  "wellknown"
                ], 
                "type": "string", 
                "description": "Specifies the type of persona, which must be combined with a name."
              }, 
              "id": {
                "type": "string", 
                "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
              }, 
              "name": {
                "type": "string", 
                "description": "Specifies the persona name, which must be combined with a type."
              }
            }
          }, 
          "type": "array", 
          "description": "Allow account to run as root."
        }, 
        "permissions": {
          "items": {
            "type": "object", 
            "description": "Specifies properties for an Access Control Entry.", 
            "properties": {
              "permission_type": {
                "enum": [
                  "allow", 
                  "deny"
                ], 
                "type": "string", 
                "description": "Determines whether the permission is allowed or denied.", 
                "required": true
              }, 
              "trustee": {
                "required": true, 
                "type": "object", 
                "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                "properties": {
                  "type": {
                    "enum": [
                      "user", 
                      "group", 
                      "wellknown"
                    ], 
                    "type": "string", 
                    "description": "Specifies the type of persona, which must be combined with a name."
                  }, 
                  "id": {
                    "type": "string", 
                    "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
                  }, 
                  "name": {
                    "type": "string", 
                    "description": "Specifies the persona name, which must be combined with a type."
                  }
                }
              }, 
              "permission": {
                "enum": [
                  "full", 
                  "change", 
                  "read"
                ], 
                "type": "string", 
                "description": "Specifies the file system rights that are allowed or denied.", 
                "required": true
              }
            }
          }, 
          "type": "array", 
          "description": "Specifies an ordered list of permission modifications."
        }, 
        "name": {
          "required": true, 
          "type": "string", 
          "description": "Share name."
        }, 
        "host_acl": {
          "items": {
            "type": "string", 
            "description": "<'allow:'|'deny:'><'ALL'|IP-range|subnet|fqdn>[' EXCEPT '<IP-range|subnet|fqdn>]."
          }, 
          "type": "array", 
          "description": "An ACL expressing which hosts are allowed access. A deny clause must be the final entry."
        }, 
        "change_notify": {
          "enum": [
            "all", 
            "norecurse", 
            "none"
          ], 
          "type": "string", 
          "description": "Level of change notification alerts on the share."
        }, 
        "mangle_byte_start": {
          "type": "integer", 
          "description": "Specifies the wchar_t starting point for automatic byte mangling."
        }, 
        "impersonate_user": {
          "type": "string", 
          "description": "User account to be used as guest account."
        }, 
        "create_path": {
          "type": "boolean", 
          "description": "Create path if does not exist."
        }, 
        "impersonate_guest": {
          "enum": [
            "always", 
            "bad user", 
            "never"
          ], 
          "type": "string", 
          "description": "Specify the condition in which user access is done as the guest account."
        }, 
        "oplocks": {
          "type": "boolean", 
          "description": "Support oplocks."
        }, 
        "strict_flush": {
          "type": "boolean", 
          "description": "Handle SMB flush operations."
        }, 
        "strict_ca_lockout": {
          "type": "boolean", 
          "description": "Specifies if persistent opens would do strict lockout on the share."
        }
      }
    }, 
    {
      "items": {
        "required": true, 
        "type": "object", 
        "properties": {
          "file_create_mode": {
            "type": "integer", 
            "description": "File create mode bits."
          }, 
          "ntfs_acl_support": {
            "type": "boolean", 
            "description": "Support NTFS ACLs on files and directories."
          }, 
          "file_filtering_enabled": {
            "type": "boolean", 
            "description": "Enables file filtering on this zone."
          }, 
          "directory_create_mask": {
            "type": "integer", 
            "description": "Directory create mask bits."
          }, 
          "inheritable_path_acl": {
            "type": "boolean", 
            "description": "Set the inheritable ACL on the share path."
          }, 
          "ca_write_integrity": {
            "enum": [
              "none", 
              "write-read-coherent", 
              "full"
            ], 
            "type": "string", 
            "description": "Specify the level of write-integrity on continuously available shares."
          }, 
          "file_create_mask": {
            "type": "integer", 
            "description": "File create mask bits."
          }, 
          "path": {
            "required": true, 
            "type": "string", 
            "description": "Path of share within /ifs."
          }, 
          "access_based_enumeration_root_only": {
            "type": "boolean", 
            "description": "Access-based enumeration on only the root directory of the share."
          }, 
          "allow_variable_expansion": {
            "type": "boolean", 
            "description": "Allow automatic expansion of variables for home directories."
          }, 
          "hide_dot_files": {
            "type": "boolean", 
            "description": "Hide files and directories that begin with a period '.'."
          }, 
          "create_permissions": {
            "enum": [
              "default acl", 
              "inherit mode bits", 
              "use create mask and mode"
            ], 
            "type": "string", 
            "description": "Create permissions for new files and directories in share."
          }, 
          "strict_locking": {
            "type": "boolean", 
            "description": "Specifies whether byte range locks contend against SMB I/O."
          }, 
          "zone": {
            "type": "string", 
            "description": "Name of the access zone to which to move this SMB share"
          }, 
          "mangle_map": {
            "items": {
              "type": "string"
            }, 
            "type": "array", 
            "description": "Character mangle map."
          }, 
          "file_filter_type": {
            "enum": [
              "deny", 
              "allow"
            ], 
            "type": "string", 
            "description": "Specifies if filter list is for deny or allow. Default is deny."
          }, 
          "file_filter_extensions": {
            "items": {
              "type": "string"
            }, 
            "type": "array", 
            "description": "Specifies the list of file extensions."
          }, 
          "browsable": {
            "type": "boolean", 
            "description": "Share is visible in net view and the browse list."
          }, 
          "description": {
            "type": "string", 
            "description": "Description for this SMB share."
          }, 
          "auto_create_directory": {
            "type": "boolean", 
            "description": "Automatically create home directories."
          }, 
          "continuously_available": {
            "type": "boolean", 
            "description": "Specify if persistent opens are allowed on the share."
          }, 
          "directory_create_mode": {
            "type": "integer", 
            "description": "Directory create mode bits."
          }, 
          "allow_delete_readonly": {
            "type": "boolean", 
            "description": "Allow deletion of read-only files in the share."
          }, 
          "ca_timeout": {
            "minimum": 2, 
            "type": "integer", 
            "description": "Persistent open timeout for the share."
          }, 
          "access_based_enumeration": {
            "type": "boolean", 
            "description": "Only enumerate files and folders the requesting user has access to."
          }, 
          "allow_execute_always": {
            "type": "boolean", 
            "description": "Allows users to execute files they have read rights for."
          }, 
          "csc_policy": {
            "enum": [
              "manual", 
              "documents", 
              "programs", 
              "none"
            ], 
            "type": "string", 
            "description": "Client-side caching policy for the shares."
          }, 
          "run_as_root": {
            "items": {
              "type": "object", 
              "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
              "properties": {
                "type": {
                  "enum": [
                    "user", 
                    "group", 
                    "wellknown"
                  ], 
                  "type": "string", 
                  "description": "Specifies the type of persona, which must be combined with a name."
                }, 
                "id": {
                  "type": "string", 
                  "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
                }, 
                "name": {
                  "type": "string", 
                  "description": "Specifies the persona name, which must be combined with a type."
                }
              }
            }, 
            "type": "array", 
            "description": "Allow account to run as root."
          }, 
          "permissions": {
            "items": {
              "type": "object", 
              "description": "Specifies properties for an Access Control Entry.", 
              "properties": {
                "permission_type": {
                  "enum": [
                    "allow", 
                    "deny"
                  ], 
                  "type": "string", 
                  "description": "Determines whether the permission is allowed or denied.", 
                  "required": true
                }, 
                "trustee": {
                  "required": true, 
                  "type": "object", 
                  "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                  "properties": {
                    "type": {
                      "enum": [
                        "user", 
                        "group", 
                        "wellknown"
                      ], 
                      "type": "string", 
                      "description": "Specifies the type of persona, which must be combined with a name."
                    }, 
                    "id": {
                      "type": "string", 
                      "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'."
                    }, 
                    "name": {
                      "type": "string", 
                      "description": "Specifies the persona name, which must be combined with a type."
                    }
                  }
                }, 
                "permission": {
                  "enum": [
                    "full", 
                    "change", 
                    "read"
                  ], 
                  "type": "string", 
                  "description": "Specifies the file system rights that are allowed or denied.", 
                  "required": true
                }
              }
            }, 
            "type": "array", 
            "description": "Specifies an ordered list of permission modifications."
          }, 
          "name": {
            "required": true, 
            "type": "string", 
            "description": "Share name."
          }, 
          "host_acl": {
            "items": {
              "type": "string", 
              "description": "<'allow:'|'deny:'><'ALL'|IP-range|subnet|fqdn>[' EXCEPT '<IP-range|subnet|fqdn>]."
            }, 
            "type": "array", 
            "description": "An ACL expressing which hosts are allowed access. A deny clause must be the final entry."
          }, 
          "change_notify": {
            "enum": [
              "all", 
              "norecurse", 
              "none"
            ], 
            "type": "string", 
            "description": "Level of change notification alerts on the share."
          }, 
          "mangle_byte_start": {
            "type": "integer", 
            "description": "Specifies the wchar_t starting point for automatic byte mangling."
          }, 
          "impersonate_user": {
            "type": "string", 
            "description": "User account to be used as guest account."
          }, 
          "create_path": {
            "type": "boolean", 
            "description": "Create path if does not exist."
          }, 
          "impersonate_guest": {
            "enum": [
              "always", 
              "bad user", 
              "never"
            ], 
            "type": "string", 
            "description": "Specify the condition in which user access is done as the guest account."
          }, 
          "oplocks": {
            "type": "boolean", 
            "description": "Support oplocks."
          }, 
          "strict_flush": {
            "type": "boolean", 
            "description": "Handle SMB flush operations."
          }, 
          "strict_ca_lockout": {
            "type": "boolean", 
            "description": "Specifies if persistent opens would do strict lockout on the share."
          }
        }
      }, 
      "type": "array"
    }
  ], 
  "description": "An array of ids to refer newly created SMB shares."
}

POST response body schema:
{
  "type": [
    {
      "type": "object", 
      "properties": {
        "id": {
          "required": true, 
          "type": "string", 
          "description": "ID of created item that can be used to refer to item in the collection-item resource path."
        }
      }
    }, 
    {
      "items": {
        "type": "object", 
        "properties": {
          "id": {
            "required": true, 
            "type": "string", 
            "description": "ID of created item that can be used to refer to item in the collection-item resource path."
          }
        }
      }, 
      "type": "array"
    }
  ]
}

********************************************************************************

Method DELETE: Delete multiple smb shares.

          URL: DELETE /platform/<<version=3>>/protocols/smb/shares

There are no query arguments for this method.

There is no response body for this method.
