Branches: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

Create a branch and redirect a site owner for editing

You can create a new branch for a site owner to edit and provide a button that directs them to the editor to make changes. This is useful when building apps that let site owners test changes in an isolated environment before applying them to their live site.

To create a branch and redirect a site owner for editing:

1. Call Create Branch. Specify a name for the branch and set the sourceType to SOURCE_BRANCH with sourceBranchProperties containing the ID of the branch to copy from (typically the site's original branch or current working branch). Collect the branch id from the response.

2. Call Get Editor URLs to retrieve the appropriate editor URL for the site.

3. Append the branch ID as a query parameter to the editor URL. For example:

   Copy

4. Display a button or link in your app interface. When the site owner clicks it, redirect them to the generated URL to begin editing the new branch.

Organize branches using tags

You can use tags to organize and categorize branches across multiple sites, making it easier to manage test sites at scale. This is useful when building apps that help agencies or developers manage branches across many client sites.

To organize branches using tags:

1. Define a tagging strategy for your use case. For example, use tags like ready-for-review, qa-testing, or client-approved.
2. When creating a branch with Create Branch, include initial tags in the tags field of the branch object.
3. To update tags on existing branches, choose the appropriate method based on your needs:
   • Single branch: Call Update Branch with the updated tags field. Make sure to include the current revision number to prevent conflicting changes.
   • Multiple specific branches: Call Bulk Update Branch Tags with an array of branch IDs and specify which tags to assign or unassign. The response includes the result for each branch, including any errors.
   • Branches matching criteria: Call Bulk Update Branch Tags by Filter with a filter and specify which tags to assign or unassign. This method runs asynchronously and returns a job ID for tracking the operation's progress.
4. To filter branches by tags, call Query Branches with a filter on the tags field to retrieve branches that match your tagging criteria.