namespace files


#
# Property Group routes
#

route properties/add(PropertyGroupWithPath, Void, AddPropertiesError)
    "Add custom properties to a file using a filled property template.
    See properties/template/add to create new property templates."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

route properties/overwrite(PropertyGroupWithPath, Void, InvalidPropertyGroupError)
    "Overwrite custom properties from a specified template
    associated with a file."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

route properties/update(UpdatePropertyGroupArg, Void, UpdatePropertiesError)
    "Add, update or remove custom properties from a specified template
    associated with a file. Fields that already exist and not described in
    the request will not be modified."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

route properties/remove(RemovePropertiesArg, Void, RemovePropertiesError)
    "Remove all custom properties from a specified template associated with a file.
    To remove specific property key value pairs, see :route:`properties/update`.
    To update a property template, see properties/template/update.
    Property templates can't be removed once created."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

route properties/template/get(properties.GetPropertyTemplateArg, properties.GetPropertyTemplateResult, properties.PropertyTemplateError)
    "Get the schema for a specified template."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

route properties/template/list(Void, properties.ListPropertyTemplateIds, properties.PropertyTemplateError)
    "Get the property template identifiers for a user. To get the schema of
    each template use :route:`properties/template/get`."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

struct RemovePropertiesArg
    path PathOrId
        "A unique identifier for the file."
    property_template_ids List(properties.TemplateId)
        "A list of identifiers for a property template created by route properties/template/add."

    example default
        path = "/my_awesome/word.docx"
        property_template_ids = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]

struct PropertyGroupWithPath
    path PathOrId
        "A unique identifier for the file."
    property_groups List(properties.PropertyGroup)
        "Filled custom property templates associated with a file."

    example default
        path = "/my_awesome/word.docx"
        property_groups = [default]

struct UpdatePropertyGroupArg
    path PathOrId
        "A unique identifier for the file."
    update_property_groups List(PropertyGroupUpdate)
        "Filled custom property templates associated with a file."

    example default
        path = "/my_awesome/word.docx"
        update_property_groups = [default]

struct PropertyGroupUpdate
    template_id properties.TemplateId
        "A unique identifier for a property template."
    add_or_update_fields List(properties.PropertyField)?
        "List of property fields to update if the field already exists. If the field doesn't exist,
        add the field to the property group."
    remove_fields List(String)?
        "List of property field names to remove from property group if the field exists."

    example default
        template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        add_or_update_fields = [default]
        remove_fields = []

union AddPropertiesError extends InvalidPropertyGroupError
    property_group_already_exists
        "This property group already exists for this file."

union UpdatePropertiesError extends InvalidPropertyGroupError
    property_group_lookup LookUpPropertiesError

union RemovePropertiesError extends PropertiesError
    property_group_lookup LookUpPropertiesError

union_closed LookUpPropertiesError
    property_group_not_found
        "This property group does not exist for this file."

union InvalidPropertyGroupError extends PropertiesError
    property_field_too_large
        "A field value in this property group is too large."
    does_not_fit_template
        "The property group specified does not conform to the property template."

union PropertiesError extends properties.PropertyTemplateError
    path LookupError

#
# Patched /get_metadata that can return properties
#

route alpha/get_metadata (AlphaGetMetadataArg, Metadata, AlphaGetMetadataError)
    "Returns the metadata for a file or folder. This is an alpha endpoint
    compatible with the properties API.

    Note: Metadata for the root folder is unsupported."

    attrs
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

struct AlphaGetMetadataArg extends GetMetadataArg
    include_property_templates List(properties.TemplateId)?
        "If set to a valid list of template IDs,
        :field:`FileMetadata.property_groups` is set for files with custom
        properties."

    example default
        path = "/Homework/math"

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

union_closed AlphaGetMetadataError extends GetMetadataError
    properties_error LookUpPropertiesError

#
# Patched /upload that accepts properties
#

route alpha/upload (CommitInfoWithProperties, FileMetadata, UploadErrorWithProperties)
    "Create a new file with the contents provided in the request. Note that this
    endpoint is part of the properties API alpha and is slightly different from
    :route:`upload`.

    Do not use this to upload a file larger than 150 MB. Instead, create an
    upload session with :route:`upload_session/start`."

    attrs
        host="content"
        style="upload"
        api_group="properties"
        is_preview=true
        allow_app_folder_app = true

struct CommitInfoWithProperties extends CommitInfo
    property_groups List(properties.PropertyGroup)?
        "List of custom properties to add to file."

    example default
        path = "/Homework/math/Matrices.txt"
        autorename = true
        property_groups = [default]

union UploadErrorWithProperties extends UploadError
    properties_error InvalidPropertyGroupError