Package com.xebialabs.xlrelease.api.v1

# Interface FolderApi

All Superinterfaces:
  `ApiService`

@Path("/api/v1/folders") @Produces("application/json") @Consumes("application/json") public interface FolderApi extends ApiService
Operations on folders.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `EXPRESSION_FOLDER_ID`

  ### Fields inherited from interface com.xebialabs.xlrelease.api.ApiService

  `DEFAULT_RESULTS_PER_PAGE, DEFAULT_RESULTS_PER_PAGE_STRING, DEPTH, ORDER_BY, PAGE, PAGE_IS_OFFSET, RESULTS_PER_PAGE, ROLE_IDS_DATA`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Folder`
  `addFolder(String parentId, Folder folder)`
  Adds a new folder inside the specified folder.
  `void`
  `addPermissionsToTeamById(String folderId, String teamId, List<String> permissions)`
  `void`
  `addPermissionsToTeamByName(String folderId, String teamName, List<String> permissions)`
  `void`
  `addPrincipalsToTeamById(String folderId, String teamId, List<String> principalNames)`
  `void`
  `addPrincipalsToTeamByName(String folderId, String teamName, List<String> principalNames)`
  `void`
  `addRoleNamesToTeamById(String folderId, String teamId, List<String> roleNames)`
  `void`
  `addRoleNamesToTeamByName(String folderId, String teamName, List<String> roleNames)`
  `String`
  `createTeam(String folderId, CreateTeam createTeam)`
  `default String`
  `createTeam(String folderId, String name, List<String> principals, List<String> roles, List<String> permissions)`
  `Variable`
  `createVariable(String folderId, Variable variable)`
  Adds a folder variable.
  `void`
  `delete(String folderId)`
  Deletes the specified folder and all the contents inside.
  `void`
  `deleteTeamById(String folderId, String teamId)`
  `void`
  `deleteTeamByName(String folderId, String teamName)`
  `void`
  `deleteVariable(String folderId, String variableId)`
  Deletes a folder variable.
  `Folder`
  `find(String path, Integer depth)`
  Finds a folder from a given path.
  `Team`
  `findTeam(String folderId, String teamName)`
  `Folder`
  `getFolder(String folderId)`
  Returns the specified folder with default depth.
  `Folder`
  `getFolder(String folderId, Integer depth)`
  Returns the specified folder.
  `List<String>`
  `getPermissions()`
  Returns possible permissions.
  `Team`
  `getTeam(String folderId, String teamId)`
  `List<TeamView>`
  `getTeams(String folderId)`
  Returns folder effective teams.
  `List<Release>`
  `getTemplates(String folderId)`
  Returns the templates for the given folder with default pagination and depth.
  `default List<Release>`
  `getTemplates(String folderId, Long page, Long resultPerPage)`
  Returns the templates for the given folder.
  `default List<Release>`
  `getTemplates(String folderId, Long page, Long resultPerPage, Integer depth)`
  Deprecated.
  Since 24.1.0.
  `List<Release>`
  `getTemplates(String folderId, String kind, Long page, Long resultPerPage)`
  Returns the list of release or workflow templates for the given folder.
  `List<Release>`
  `getTemplates(String folderId, String kind, Long page, Long resultPerPage, Integer depth)`
  Deprecated.
  Since 24.1.0.
  `Variable`
  `getVariable(String folderId, String variableId)`
  Returns the folder variable for the given identifier.
  `boolean`
  `isFolderOwner(String folderId)`
  `List<Folder>`
  `list(String parentId, Long page, Long resultPerPage, Integer depth, Boolean decorateWithPermissions)`
  Lists the folders inside a given folder.
  `default List<Folder>`
  `listRoot()`
  Returns a list of all folders directly under the root directory.
  `List<Folder>`
  `listRoot(Long page, Long resultPerPage, Integer depth, Boolean decorateWithPermissions)`
  Returns a list of folders from the root directory.
  `List<Variable>`
  `listVariables(String folderId, boolean folderOnly)`
  Returns folder variables list.
  `Map<String,String>`
  `listVariableValues(String folderId, boolean folderOnly)`
  Returns folder variables list with replaced variable values.
  `void`
  `move(String folderId, String newParentId)`
  Move a folder to another folder.
  `void`
  `moveTemplate(String folderId, String templateId)`
  Move a template to another folder without merging permissions.
  `void`
  `moveTemplate(String folderId, String templateId, Boolean mergeTeams)`
  Move a template to another folder.
  `void`
  `removePermissionsFromTeamById(String folderId, String teamId, List<String> permissions)`
  `void`
  `removePermissionsFromTeamByName(String folderId, String teamName, List<String> permissions)`
  `void`
  `removePrincipalsFromTeamById(String folderId, String teamId, List<String> principalNames)`
  `void`
  `removePrincipalsFromTeamByName(String folderId, String teamName, List<String> principalNames)`
  `void`
  `removeRoleNamesFromTeamById(String folderId, String teamId, List<String> roleNames)`
  `void`
  `removeRoleNamesFromTeamByName(String folderId, String teamName, List<String> roleNames)`
  `void`
  `rename(String folderId, String newName)`
  Rename a folder.
  `List<Release>`
  `searchReleases(String folderId, ReleasesFilters releasesFilters)`
  Returns the releases started from this folder with default pagination and depth.
  `List<Release>`
  `searchReleases(String folderId, Long page, Long resultPerPage, ReleasesFilters releasesFilters)`
  Returns the releases started from this folder.
  `List<Release>`
  `searchReleases(String folderId, Long page, Long resultPerPage, Integer depth, ReleasesFilters releasesFilters)`
  Deprecated.
  Since 24.1.0.
  `default String`
  `serviceName()`
  `List<TeamView>`
  `setTeams(String folderId, List<TeamView> teamDtos)`
  Set teams of the folder.
  `Variable`
  `updateVariable(String folderId, Variable variable)`
  Updates properties of a folder variable by its ID.
  `Variable`
  `updateVariable(String folderId, String variableId, Variable variable)`

- ## Field Details

  - ### EXPRESSION_FOLDER_ID

    static final String EXPRESSION_FOLDER_ID
    See Also:
      - Constant Field Values

- ## Method Details

  - ### serviceName

    default String serviceName()
    Specified by:
      `serviceName` in interface `ApiService`

  - ### listRoot

    @GET @Path("/list") List<Folder> listRoot(@QueryParam("page") Long page, @QueryParam("resultsPerPage") Long resultPerPage, @QueryParam("depth") Integer depth, @QueryParam("permissions") Boolean decorateWithPermissions)
    Returns a list of folders from the root directory.
    Parameters:
      `page` - the page of results to return. Defaults at 0 if page set to null
      `resultPerPage` - the number of results per page. Defaults at 50 if set to null
      `depth` - the depth to search for. Defaults at 1 if set to null
      `decorateWithPermissions` - the boolean to decorate the folders with the effective permissions. Defaults to false if set to null
    Returns:
      a list of the folders

  - ### listRoot

    default List<Folder> listRoot()
    Returns a list of all folders directly under the root directory.
    Returns:
      a list of the folders

  - ### list

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/list") List<Folder> list(@PathParam("folderId") String parentId, @QueryParam("page") Long page, @QueryParam("resultsPerPage") Long resultPerPage, @QueryParam("depth") Integer depth, @QueryParam("permissions") Boolean decorateWithPermissions)
    Lists the folders inside a given folder.
    Parameters:
      `parentId` - the parent folder to retrieve from
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
      `depth` - the depth to search for. Defaults at 1
    Returns:
      the list of folders beneath a given folder

  - ### find

    @GET @Path("/find") Folder find(@QueryParam("byPath") String path, @QueryParam("depth") Integer depth)
    Finds a folder from a given path.
    Parameters:
      `path` - the path for the folder to search on
      `depth` - the depth to search for. Defaults at 1
    Returns:
      the folder found in the path

  - ### getFolder

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}") Folder getFolder(@PathParam("folderId") String folderId, @QueryParam("depth") Integer depth)
    Returns the specified folder.
    Parameters:
      `folderId` - the id of the folder
      `depth` - the depth to search for. Defaults at 1
    Returns:
      the specified folder

  - ### getFolder

    Folder getFolder(String folderId)
    Returns the specified folder with default depth.
    Parameters:
      `folderId` - the folder id
    Returns:
      the given folder

  - ### getTemplates

    @Deprecated(since="24.1.0") @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/templates") List<Release> getTemplates(@PathParam("folderId") String folderId, @DefaultValue("RELEASE") @QueryParam("kind") String kind, @QueryParam("page") Long page, @QueryParam("resultsPerPage") Long resultPerPage, @QueryParam("depth") Integer depth)
    Deprecated.
    Since 24.1.0. Please use `getTemplates(String, String, Long, Long)`
    Returns the list of release or workflow templates for the given folder.
    Parameters:
      `folderId` - the id of the folder
      `kind` - the kind of template. Default value is release.
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
      `depth` - the (optional) depth to search for; defaults at 1
    Returns:
      the list of templates in the folder

  - ### getTemplates

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/templates") List<Release> getTemplates(@PathParam("folderId") String folderId, @DefaultValue("RELEASE") @QueryParam("kind") String kind, @QueryParam("page") Long page, @QueryParam("resultsPerPage") Long resultPerPage)
    Returns the list of release or workflow templates for the given folder.
    Parameters:
      `folderId` - the id of the folder
      `kind` - the kind of template. Default value is release.
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
    Returns:
      the list of templates in the folder

  - ### getTemplates

    @Deprecated(since="24.1.0") default List<Release> getTemplates(String folderId, Long page, Long resultPerPage, Integer depth)
    Deprecated.
    Since 24.1.0. Please use `getTemplates(String, Long, Long)`
    Returns the templates for the given folder.
    Parameters:
      `folderId` - the id of the folder
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
      `depth` - the (optional) depth to search for; defaults at 1
    Returns:
      the list of templates in the folder

  - ### getTemplates

    default List<Release> getTemplates(String folderId, Long page, Long resultPerPage)
    Returns the templates for the given folder.
    Parameters:
      `folderId` - the id of the folder
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
    Returns:
      the list of templates in the folder

  - ### getTemplates

    List<Release> getTemplates(String folderId)
    Returns the templates for the given folder with default pagination and depth.
    Parameters:
      `folderId` - the folder id
    Returns:
      the list of templates in the folder

  - ### searchReleases

    @Deprecated(since="24.1.0") @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/releases") List<Release> searchReleases(@PathParam("folderId") String folderId, @QueryParam("page") Long page, @QueryParam("numberbypage") Long resultPerPage, @QueryParam("depth") Integer depth, ReleasesFilters releasesFilters)
    Deprecated.
    Since 24.1.0. Please use `searchReleases(String, Long, Long, ReleasesFilters)`
    Returns the releases started from this folder.
    Parameters:
      `folderId` - the id of the folder
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
      `depth` - the depth to search for
      `releasesFilters` - releaseFilter to filter the release search
    Returns:
      the list of releases

  - ### searchReleases

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/releases") List<Release> searchReleases(@PathParam("folderId") String folderId, @QueryParam("page") Long page, @QueryParam("numberbypage") Long resultPerPage, ReleasesFilters releasesFilters)
    Returns the releases started from this folder.
    Parameters:
      `folderId` - the id of the folder
      `page` - the page of results to return. Defaults at 0
      `resultPerPage` - the number of results per page. Defaults at 50
      `releasesFilters` - releaseFilter to filter the release search
    Returns:
      the list of releases

  - ### searchReleases

    List<Release> searchReleases(String folderId, ReleasesFilters releasesFilters)
    Returns the releases started from this folder with default pagination and depth.
    Parameters:
      `folderId` - the folder id
      `releasesFilters` - the releaseFilters to filter the release search on
    Returns:
      the list of releases in a folder

  - ### moveTemplate

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/templates/{templateId:.*Release[^/]*}") void moveTemplate(@PathParam("folderId") String folderId, @PathParam("templateId") String templateId, @QueryParam("mergePermissions") Boolean mergeTeams)
    Move a template to another folder.
    Parameters:
      `folderId` - the target folder the template will be moved to
      `templateId` - the id of the template to be moved

  - ### moveTemplate

    void moveTemplate(String folderId, String templateId)
    Move a template to another folder without merging permissions.
    Parameters:
      `folderId` - the id of the parent folder
      `templateId` - the id of the template to be moved

  - ### addFolder

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}") Folder addFolder(@PathParam("folderId") String parentId, Folder folder)
    Adds a new folder inside the specified folder.
    Parameters:
      `parentId` - the id of the folder to create the folder in
      `folder` - the folder to create the new folder in
    Returns:
      the newly created folder

  - ### delete

    @DELETE @Path("/{folderId:.*(Folder[^/]*|Applications)}") void delete(@PathParam("folderId") String folderId)
    Deletes the specified folder and all the contents inside.
    Parameters:
      `folderId` - the id of the folder to delete

  - ### move

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/move") void move(@PathParam("folderId") String folderId, @QueryParam("newParentId") String newParentId)
    Move a folder to another folder. Following restrictions apply to folder being moved: it must not contain any scheduled or running releases, the folder and all its children must not contain any triggers, and it must not contain any releases with references to connections not available under new parent folder.
    Parameters:
      `folderId` - the id of the folder to move
      `newParentId` - the id of the parent folder the folder will be moved under

  - ### rename

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/rename") void rename(@PathParam("folderId") String folderId, @QueryParam("newName") String newName)
    Rename a folder.
    Parameters:
      `folderId` - the id of the folder to rename
      `newName` - the new name of the folder

  - ### getPermissions

    @GET @Path("/permissions") List<String> getPermissions()
    Returns possible permissions.
    Returns:
      list of permissions for folders, templates and releases

  - ### getTeams

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams") List<TeamView> getTeams(@PathParam("folderId") String folderId)
    Returns folder effective teams.
    Parameters:
      `folderId` - the id of the folder
    Returns:
      list of effective teams

  - ### setTeams

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams") List<TeamView> setTeams(@PathParam("folderId") String folderId, List<TeamView> teamDtos)
    Set teams of the folder.

    If teams were previously inherited they will be detached after the update. To use inherited teams on a folder submit empty list of teams.

    Parameters:
      `folderId` - the identifier of the folder
    Returns:
      a list of updated teams

  - ### isFolderOwner

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/folderOwner") boolean isFolderOwner(@PathParam("folderId") String folderId)

  - ### listVariables

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/variables") List<Variable> listVariables(@PathParam("folderId") String folderId, @QueryParam("folderOnly") boolean folderOnly)
    Returns folder variables list.
    Parameters:
      `folderId` - the folder identifier.
      `folderOnly` - filter if you only want to get information from your parentId. (optional)
    Returns:
      variables list.

  - ### listVariableValues

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/variableValues") Map<String,String> listVariableValues(@PathParam("folderId") String folderId, @QueryParam("folderOnly") boolean folderOnly)
    Returns folder variables list with replaced variable values.
    Parameters:
      `folderId` - the folder identifier.
      `folderOnly` - filter if you only want to get information from your parentId. (optional)
    Returns:
      variables list.

  - ### createVariable

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/variables") Variable createVariable(@PathParam("folderId") String folderId, Variable variable)
    Adds a folder variable.
    Parameters:
      `folderId` - the folder identifier.
      `variable` - the folder variable to add.
    Returns:
      the added folder variable.

  - ### getVariable

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/{variableId:.*Variable[^/]*}") Variable getVariable(@PathParam("folderId") String folderId, @PathParam("variableId") String variableId)
    Returns the folder variable for the given identifier.
    Parameters:
      `folderId` - the folder identifier.
      `variableId` - the variable identifier.
    Returns:
      the variable.

  - ### updateVariable

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{variableId:.*Variable[^/]*}") Variable updateVariable(@PathParam("folderId") String folderId, @PathParam("variableId") String variableId, Variable variable)

  - ### updateVariable

    Variable updateVariable(String folderId, Variable variable)
    Updates properties of a folder variable by its ID.
    Parameters:
      `folderId` - the folder identifier.
      `variable` - the variable to update.
    Returns:
      the updated variable.

  - ### deleteVariable

    @DELETE @Path("/{folderId:.*(Folder[^/]*|Applications)}/{variableId:.*Variable[^/]*}") void deleteVariable(@PathParam("folderId") String folderId, @PathParam("variableId") String variableId)
    Deletes a folder variable.
    Parameters:
      `folderId` - the folder identifier.
      `variableId` - the variable identifier.

  - ### getTeam

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}") Team getTeam(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId)

  - ### findTeam

    @GET @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}") Team findTeam(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName)

  - ### createTeam

    @POST @Path("/{folderId:.*(Folder[^/]*|Applications)}/create-team") String createTeam(@PathParam("folderId") String folderId, CreateTeam createTeam)

  - ### createTeam

    default String createTeam(String folderId, String name, List<String> principals, List<String> roles, List<String> permissions)

  - ### deleteTeamByName

    @DELETE @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}") void deleteTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName)

  - ### deleteTeamById

    @DELETE @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}") void deleteTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId)

  - ### addPrincipalsToTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/add-principals") void addPrincipalsToTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> principalNames)

  - ### addPrincipalsToTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/add-principals") void addPrincipalsToTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> principalNames)

  - ### removePrincipalsFromTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/remove-principals") void removePrincipalsFromTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> principalNames)

  - ### removePrincipalsFromTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/remove-principals") void removePrincipalsFromTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> principalNames)

  - ### addRoleNamesToTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/add-roles") void addRoleNamesToTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> roleNames)

  - ### addRoleNamesToTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/add-roles") void addRoleNamesToTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> roleNames)

  - ### removeRoleNamesFromTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/remove-roles") void removeRoleNamesFromTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> roleNames)

  - ### removeRoleNamesFromTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/remove-roles") void removeRoleNamesFromTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> roleNames)

  - ### addPermissionsToTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/add-permissions") void addPermissionsToTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> permissions)

  - ### addPermissionsToTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/add-permissions") void addPermissionsToTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> permissions)

  - ### removePermissionsFromTeamById

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/{teamId:Team[^/]*}/remove-permissions") void removePermissionsFromTeamById(@PathParam("folderId") String folderId, @PathParam("teamId") String teamId, List<String> permissions)

  - ### removePermissionsFromTeamByName

    @PUT @Path("/{folderId:.*(Folder[^/]*|Applications)}/teams/{teamName}/remove-permissions") void removePermissionsFromTeamByName(@PathParam("folderId") String folderId, @PathParam("teamName") String teamName, List<String> permissions)