Package com.xebialabs.xlrelease.api.v1

# Interface FolderVersioningApi

All Superinterfaces:
  `ApiService`

@Path("api/v1/version-control") @Produces("application/json") @Consumes("application/json") public interface FolderVersioningApi extends ApiService
Operations to store and synchronize folder contents - templates, workflows, connections, variables, and more - as YAML files in Git for version tracking.

- ## Field Summary

  ### 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
  `ValidationReport`
  `applyVersion(String folderId, String version)`
  Applies the specified version to the given folder.
  `void`
  `clearSecrets(String folderId)`
  `VersionInfo`
  `createVersion(String folderId, CreateVersionForm versionForm)`
  `VersionInfo`
  `createVersion(String folderId, String versionName, String description)`
  Creates a new version for the specified folder using the provided version name and description.
  `void`
  `deleteLocalRepo(String folderId)`
  `void`
  `deleteLocalRepo(String folderId, Boolean clusterWide)`
  `void`
  `deleteSettings(String folderId)`
  Deletes the Git versioning settings and versioned history for the specified folder.
  `List<GitBranch>`
  `getAllBranches(String folderId, String configId)`
  Retrieves all branches associated with the specified folder.
  `List<String>`
  `getCurrentVersionableFileNames(String folderId)`
  Retrieves the list of file names that are currently versionable in the specified folder given the versioning settings for the folder.
  `FolderVersioningSettings`
  `getSettings(String folderId)`
  Retrieves the Git versioning settings for the specified folder.
  `ValidationReportMessage`
  `getValidationMessage(String folderId, String messageId)`
  Retrieves a specific validation message for the given folder and message ID for passwords or unversioned references.
  `ValidationReport`
  `getValidationMessages(String folderId)`
  Retrieves the validation messages for the currently applied version for the specified folder.
  `List<String>`
  `getVersionedFileNames(String folderId, String version)`
  Returns the list of file names that are associated with the specified version of a folder.
  `List<VersioningStyle>`
  `getVersioningStyles()`
  Retrieves the list of available versioning styles.
  `VersionsView`
  `getVersions(String folderId)`
  Retrieves all versions associated with the specified folder.
  `VersionsView`
  `getVersions(String folderId, Boolean fetchChanges)`
  Retrieves all versions associated with the specified folder.
  `String`
  `previewCurrent(String folderId, String filename)`
  Returns a YAML preview of the current state of the specified folder.
  `String`
  `previewVersion(String folderId, String version, String filename)`
  Returns a YAML preview of the specified version of the folder.
  `void`
  `resetLocalRepo(String folderId, Boolean clusterWide)`
  `default String`
  `serviceName()`
  `void`
  `setValidationMessages(String folderId, ValidationReport validationReport)`
  Sets the validation messages for the specified folder.
  `void`
  `setValidationMessagesStatus(String folderId, String messageId, ValidationReportMessage validationMessage)`
  Updates the status of a specific validation message for the given folder and message ID.
  `FolderVersioningSettings`
  `updateSettings(String folderId, FolderVersioningSettings config)`
  Updates the Git versioning settings for the specified folder.
  `ValidationReport`
  `validateCurrent(String folderId)`
  Validates the current state of the specified folder to identify issues with password or unreferenced variables that would be present if the folder were versioned.

- ## Method Details

  - ### serviceName

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

  - ### getSettings

    @GET @Path("/{folderId:.*Folder[^/-]*}/") FolderVersioningSettings getSettings(@PathParam("folderId") String folderId)
    Retrieves the Git versioning settings for the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder whose versioning settings are to be retrieved.
    Returns:
      the current versioning settings associated with the folder.

  - ### updateSettings

    @PUT @Path("/{folderId:.*Folder[^/-]*}/") FolderVersioningSettings updateSettings(@PathParam("folderId") String folderId, FolderVersioningSettings config)
    Updates the Git versioning settings for the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder to update versioning settings for.
      `config` - the new versioning configuration to apply.
    Returns:
      the updated versioning settings for the folder.

  - ### deleteSettings

    @DELETE @Path("/{folderId:.*Folder[^/-]*}/") void deleteSettings(@PathParam("folderId") String folderId)
    Deletes the Git versioning settings and versioned history for the specified folder. This does not affect existing data in the Git repository.
    Parameters:
      `folderId` - the unique identifier of the folder whose versioning settings should be deleted.

  - ### getVersions

    @GET @Path("/{folderId:.*Folder[^/-]*}/versions") VersionsView getVersions(@PathParam("folderId") String folderId, @DefaultValue("false") @QueryParam("fetchChanges") Boolean fetchChanges)
    Retrieves all versions associated with the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder whose versions are to be retrieved.
      `fetchChanges` - whether to fetch changes from the repository before returning versions.
    Returns:
      the list of versions for the specified folder.

  - ### getVersions

    VersionsView getVersions(String folderId)
    Retrieves all versions associated with the specified folder. Equivalent to calling getVersions(folderId, false).
    Parameters:
      `folderId` - the unique identifier of the folder whose versions are to be retrieved.
    Returns:
      the list of versions for the specified folder.

  - ### getAllBranches

    @GET @Path("/{folderId:.*Folder[^/-]*}/branches") List<GitBranch> getAllBranches(@PathParam("folderId") String folderId, @QueryParam("configId") String configId)
    Retrieves all branches associated with the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder whose branches are to be retrieved.
      `configId` - the configuration ID to filter branches (optional).
    Returns:
      a list of branches for the specified folder.

  - ### createVersion

    @POST @Path("/{folderId:.*Folder[^/-]*}/versions") VersionInfo createVersion(@PathParam("folderId") String folderId, CreateVersionForm versionForm)

  - ### createVersion

    VersionInfo createVersion(String folderId, String versionName, String description)
    Creates a new version for the specified folder using the provided version name and description.
    Parameters:
      `folderId` - the unique identifier of the folder for which the version is to be created.
      `versionName` - the name to assign to the new version; must be non-null and unique within the folder.
      `description` - a brief description of the version (maximum 256 characters).
    Returns:
      information about the newly created version.

  - ### applyVersion

    @POST @Path("/{folderId:.*Folder[^/-]*}/versions/{version:.*}/apply") ValidationReport applyVersion(@PathParam("folderId") String folderId, @PathParam("version") String version)
    Applies the specified version to the given folder.
    Parameters:
      `folderId` - the unique identifier of the folder to which the version will be applied.
      `version` - the version to apply to the folder.
    Returns:
      information regarding the application of the version, including any warnings or errors encountered during the process.

  - ### previewCurrent

    @GET @Produces("text/vnd.yaml") @Path("/{folderId:.*Folder[^/-]*}/preview") String previewCurrent(@PathParam("folderId") String folderId, @QueryParam("filename") String filename)
    Returns a YAML preview of the current state of the specified folder.
    Parameters:
      `folderId` - the id of the folder to preview.
      `filename` - the name of the file to preview (optional).
    Returns:
      a YAML string representing the current state of the folder.

  - ### previewVersion

    @GET @Produces("text/vnd.yaml") @Path("/{folderId:.*Folder[^/-]*}/versions/{version:.*}/preview") String previewVersion(@PathParam("folderId") String folderId, @PathParam("version") String version, @QueryParam("filename") String filename)
    Returns a YAML preview of the specified version of the folder.
    Parameters:
      `folderId` - the id of the folder to preview
      `version` - the version identifier to preview
      `filename` - the name of the file to preview (optional)
    Returns:
      a YAML string representing the specified version of the folder

  - ### getVersionedFileNames

    @GET @Path("/{folderId:.*Folder[^/-]*}/versions/{version:.*}/getVersionedFileNames") List<String> getVersionedFileNames(@PathParam("folderId") String folderId, @PathParam("version") String version)
    Returns the list of file names that are associated with the specified version of a folder.
    Parameters:
      `folderId` - the unique identifier of the folder for which to retrieve versioned file names.
      `version` - the version of the folder for which to retrieve file names.
    Returns:
      a list of file names present in the specified version of the folder.

  - ### getCurrentVersionableFileNames

    @GET @Path("/{folderId:.*Folder[^/-]*}/getVersionableFileNames") List<String> getCurrentVersionableFileNames(@PathParam("folderId") String folderId)
    Retrieves the list of file names that are currently versionable in the specified folder given the versioning settings for the folder.
    Parameters:
      `folderId` - the unique identifier of the folder for which to retrieve versionable file names.
    Returns:
      a list of file names that are currently versionable in the folder.

  - ### deleteLocalRepo

    @DELETE @Path("/{folderId:.*Folder[^/-]*}/delete-local-repo") void deleteLocalRepo(@PathParam("folderId") String folderId, @DefaultValue("false") @QueryParam("clusterWide") Boolean clusterWide)

  - ### deleteLocalRepo

    void deleteLocalRepo(String folderId)

  - ### resetLocalRepo

    @PUT @Path("/{folderId:.*Folder[^/-]*}/reset-local-repo") void resetLocalRepo(@PathParam("folderId") String folderId, @DefaultValue("false") @QueryParam("clusterWide") Boolean clusterWide)

  - ### validateCurrent

    @GET @Path("/{folderId:.*Folder[^/-]*}/validate") ValidationReport validateCurrent(@PathParam("folderId") String folderId)
    Validates the current state of the specified folder to identify issues with password or unreferenced variables that would be present if the folder were versioned.
    Parameters:
      `folderId` - the unique identifier of the folder to validate.
    Returns:
      information detailing the results of the validation including any warnings or errors that would occur if the folder were versioned.

  - ### getValidationMessages

    @GET @Path("/{folderId:.*Folder[^/-]*}/validation-messages") ValidationReport getValidationMessages(@PathParam("folderId") String folderId)
    Retrieves the validation messages for the currently applied version for the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder to retrieve validation messages for.
    Returns:
      information detailing the validation messages that are present for the folder.

  - ### setValidationMessages

    @PUT @Path("/{folderId:.*Folder[^/-]*}/validation-messages") void setValidationMessages(@PathParam("folderId") String folderId, ValidationReport validationReport)
    Sets the validation messages for the specified folder.
    Parameters:
      `folderId` - the unique identifier of the folder for which to set validation messages.
      `validationReport` - validation messages to associate with the folder.

  - ### getValidationMessage

    @GET @Path("/{folderId:.*Folder[^/-]*}/message/{messageId:.*}/") ValidationReportMessage getValidationMessage(@PathParam("folderId") String folderId, @PathParam("messageId") String messageId)
    Retrieves a specific validation message for the given folder and message ID for passwords or unversioned references.
    Parameters:
      `folderId` - the unique identifier of the folder containing the validation message.
      `messageId` - the unique identifier of the validation message to retrieve.
    Returns:
      the validation report message corresponding to the specified message ID in the folder

  - ### setValidationMessagesStatus

    @PUT @Path("/{folderId:.*Folder[^/-]*}/message/{messageId:.*}/update") void setValidationMessagesStatus(@PathParam("folderId") String folderId, @PathParam("messageId") String messageId, ValidationReportMessage validationMessage)
    Updates the status of a specific validation message for the given folder and message ID.
    Parameters:
      `folderId` - the unique identifier of the folder containing the validation message.
      `messageId` - the unique identifier of the validation message to update.
      `validationMessage` - the updated validation report message

  - ### clearSecrets

    @DELETE @Path("/{folderId:.*Folder[^/-]*}/clear-secrets") void clearSecrets(@PathParam("folderId") String folderId)

  - ### getVersioningStyles

    @GET @Path("/styles") List<VersioningStyle> getVersioningStyles()
    Retrieves the list of available versioning styles.
    Returns:
      a list of supported versioning styles