Package com.xebialabs.xlrelease.api.v1

# Interface PhaseApi

All Superinterfaces:
  `ApiService`

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

- ## Field Summary

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

  ### 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
  `Phase`
  `addPhase(String releaseId, Phase phase)`
  Wrapper method to add a phase to the release.
  `Phase`
  `addPhase(String releaseId, Phase phase, Integer position)`
  Adds a phase to a release.
  `Task`
  `addTask(String containerId, Task task, Integer position)`
  Adds a task to a phase or to a group task.
  `Phase`
  `copyPhase(String phaseIdToCopy, int targetPosition)`
  Copy a phase in a release.
  `void`
  `deletePhase(String phaseId)`
  Deletes the phase with the given ID.
  `Phase`
  `getPhase(String phaseId)`
  Returns the phase for the given identifier.
  `Phase`
  `newPhase()`
  Factory method to create a new instance of a phase.
  `Phase`
  `newPhase(String title)`
  Factory method to create a new instance of a Phase object.
  `List<Phase>`
  `searchPhases(String phaseTitle, String releaseId, PhaseVersion phaseVersion)`
  Search phase within a release.
  `List<Phase>`
  `searchPhasesByTitle(String phaseTitle, String releaseId)`
  Search phases in a release by title.
  `default String`
  `serviceName()`
  `Phase`
  `updatePhase(Phase phase)`
  Updates the properties of a phase.
  `Phase`
  `updatePhase(String phaseId, Phase phase)`
  Updates the properties of a phase.

- ## Field Details

  - ### SERVICE_NAME

    static final String SERVICE_NAME
    See Also:
      - Constant Field Values

- ## Method Details

  - ### serviceName

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

  - ### getPhase

    @GET @Path("/{phaseId:.*/Phase[^/]*}") Phase getPhase(@PathParam("phaseId") String phaseId)
    Returns the phase for the given identifier.
    Parameters:
      `phaseId` - the phase identifier.
    Returns:
      the phase.

  - ### updatePhase

    @PUT @Path("/{phaseId:.*/Phase[^/]*}") Phase updatePhase(@PathParam("phaseId") String phaseId, Phase phase)
    Updates the properties of a phase.
    Parameters:
      `phaseId` - the phase identifier.
      `phase` - new contents of the phase.
    Returns:
      the updated phase

  - ### updatePhase

    Phase updatePhase(Phase phase)
    Updates the properties of a phase.
    Parameters:
      `phase` - new contents of the phase.
    Returns:
      the updated Phase

  - ### addTask

    @POST @Path("/{containerId:.*/Phase.*?}/tasks") Task addTask(@PathParam("containerId") String containerId, Task task, @QueryParam("position") Integer position)
    Adds a task to a phase or to a group task. If no position is specified, then task is added to the end of the phase.
    Parameters:
      `containerId` - the phase or group task identifier
      `task` - the task to add.
      `position` - the position in the phase.task, 0-based. If left empty, then task will be added to the end of the phase.
    Returns:
      the added task

  - ### searchPhasesByTitle

    @GET @Path("/byTitle") List<Phase> searchPhasesByTitle(@QueryParam("phaseTitle") String phaseTitle, @QueryParam("releaseId") String releaseId)
    Search phases in a release by title.
    Parameters:
      `phaseTitle` - the phase title
      `releaseId` - the release identifier.
    Returns:
      A list of phases that match.

  - ### searchPhases

    @GET @Path("/search") List<Phase> searchPhases(@QueryParam("phaseTitle") String phaseTitle, @QueryParam("releaseId") String releaseId, @QueryParam("phaseVersion") PhaseVersion phaseVersion)
    Search phase within a release.

    ReleaseId is required, all other parameters are optional. Providing the optional parameters will narrow down search.

    Parameters:
      `phaseTitle` - (part of) the phase title (optionally, if not provided, all phases are returned)
      `releaseId` - the release identifier.
      `phaseVersion` - phase version (optionally, if not provided, no filtering will be applied)
    Returns:
      A list of phases that match.

  - ### addPhase

    @POST @Path("/{releaseId:.*Release[^/]*}/phase") Phase addPhase(@PathParam("releaseId") String releaseId, Phase phase, @QueryParam("position") Integer position)
    Adds a phase to a release. If no position is specified, then the phase is added as the last phase. All nested configuration items (e.g. tasks) will be removed from the provided phase.
    Parameters:
      `releaseId` - the identifier of a template/release.
      `phase` - the phase to add
      `position` - the position in the template, 0-based. If left empty, then phase will the last phase in the template
    Returns:
      add `Phase` object.

  - ### copyPhase

    @POST @Path("/{phaseId:.*/Phase[^/]*}/copy") Phase copyPhase(@PathParam("phaseId") String phaseIdToCopy, @QueryParam("targetPosition") int targetPosition)
    Copy a phase in a release.
    Parameters:
      `phaseIdToCopy` - the phase id to copy
      `targetPosition` - the position where to copy the phase to within a release. Cannot be `< 0` and also not `>= release.phases.size()`
    Returns:
      copy of a `Phase` object.

  - ### addPhase

    Phase addPhase(String releaseId, Phase phase)
    Wrapper method to add a phase to the release.
    Parameters:
      `releaseId` - the release id to add the phase to
      `phase` - the phase to add
    Returns:
      the phase object.

  - ### newPhase

    Phase newPhase()
    Factory method to create a new instance of a phase.
    Returns:
      the task object.

  - ### newPhase

    Phase newPhase(String title)
    Factory method to create a new instance of a Phase object.

    Example script which adds a custom phase to the current release:

         release = getCurrentRelease()
         phase = phaseApi.newPhase("My New Phase")
         phaseApi.addPhase(release.id, phase)

    Parameters:
      `title` - the title of the phase.
    Returns:
      the phase object.

  - ### deletePhase

    @DELETE @Path("/{phaseId:.*/Phase[^/]*}") void deletePhase(@PathParam("phaseId") String phaseId)
    Deletes the phase with the given ID.
    Parameters:
      `phaseId` - the phase identifier.