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)`
  `String`
  `compareFileVersions(String folderId, String fileName, String leftVersion, String rightVersion)`
  Compares two versions of a specified file within a given folder and returns the results highlighting the differences.
  `String`
  `compareFileVersionWithCurrent(String folderId, String fileName, String version)`
  Compares a specified version of a file with the current state of the given folder and returns the results highlighting the differences.
  `VersionComparisonView`
  `compareVersions(String folderId, String leftVersion, String rightVersion)`
  Compares two versions for a specified folder id and returns a summary of file changes in the two versions.
  `VersionComparisonView`
  `compareVersionWithCurrent(String folderId, String version)`
  Compares a specified version with the current version of the given folder and returns the results highlighting the differences.
  `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<FoldersWithAppliedVersionInfo>`
  `getVersionedFolderInfo()`
  Retrieves a list of all folders along with their currently applied version information.
  `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

  - ### compareFileVersions

    @GET @Path("/{folderId:.*Folder[^/-]*}/compare-file") String compareFileVersions(@PathParam("folderId") String folderId, @QueryParam("fileName") String fileName, @QueryParam("leftVersion") String leftVersion, @QueryParam("rightVersion") String rightVersion)
    Compares two versions of a specified file within a given folder and returns the results highlighting the differences. If either version parameter is omitted, the current version of the file will be used for that side of the comparison.
    Parameters:
      `folderId` - the unique identifier of the folder that contains the file whose versions are to be compared.
      `fileName` - the name of the file to compare.
      `leftVersion` - the version identifier of the source (left) file for comparison. If not specified, the current version is used.
      `rightVersion` - the version identifier of the target (right) file for comparison. If not specified, the current version is used.
    Returns:
      a String containing the comparison results that identify differences between the specified versions.

  - ### compareFileVersionWithCurrent

    String compareFileVersionWithCurrent(String folderId, String fileName, String version)
    Compares a specified version of a file with the current state of the given folder and returns the results highlighting the differences.
    Parameters:
      `folderId` - the unique identifier of the folder containing the file to be compared.
      `fileName` - the name of the file to compare.
      `version` - the version identifier of the file to compare against the current version.
    Returns:
      a String containing the comparison results identifying the differences between the specified version and the current version.

  - ### compareVersions

    @GET @Path("/{folderId:.*Folder[^/-]*}/compare-versions") VersionComparisonView compareVersions(@PathParam("folderId") String folderId, @QueryParam("leftVersion") String leftVersion, @QueryParam("rightVersion") String rightVersion)
    Compares two versions for a specified folder id and returns a summary of file changes in the two versions. If either version parameter is omitted, the current version of the folder will be used for that side of the comparison.
    Parameters:
      `folderId` - the unique identifier of the folder that contains the versions that are to be compared.
      `leftVersion` - the version identifier of the source (left) version for comparison. If not specified, the current version is used.
      `rightVersion` - the version identifier of the target (right) version for comparison. If not specified, the current version is used.
    Returns:
      a VersionComparisonView containing the comparison results that identify differences between the specified versions.

  - ### compareVersionWithCurrent

    VersionComparisonView compareVersionWithCurrent(String folderId, String version)
    Compares a specified version with the current version of the given folder and returns the results highlighting the differences.
    Parameters:
      `folderId` - the unique identifier of the folder to be compared.
      `version` - the version identifier of the version to be compared against the current version.
    Returns:
      a VersionComparisonView containing the comparison results that identify differences between the specified versions.

  - ### getVersionedFolderInfo

    @GET @Path("/all-folders-applied-version") List<FoldersWithAppliedVersionInfo> getVersionedFolderInfo()
    Retrieves a list of all folders along with their currently applied version information.
    Returns:
      a list of `FoldersWithAppliedVersionInfo` objects, each representing a folder and its applied version details.