Branches and environments

Learn about how branches and environments work in Appear.

Overview

The concepts of branches and environments in Appear help you effectively manage, track, and compare your API ecosystem versions across various development and deployment stages. This guide explains how these features work and how you can leverage them.

You can create new branches from the top level navigator. Environments are detected and set from you variable configuration.

Shared aspects:

Both Branches and Environments describe a version of your API model and generally contain the same type of information, however they differ in their meaning and behaviour. Branches and environments provide a layer over all services, allowing changes in one branch to impact multiple services, if applicable.

Environments

• Environments represent the current state of your deployment (e.g., production, staging, test-farm-alpha)

• The version model is inferred from the environment using an introspector which ensures it reflects actual schema.

• Unlimited Environments: You can create as many environments as needed. However, one environment will always be marked as the default, which is shown by default in the UI.

• Diff Capabilities (planned): You will be able to compare (or "diff") environments with other environments or branches. This allows you to detect inconsistencies, breaking changes, or differences in implementation.

Branches

• Branches represent the intended changes in code and are created by users directly in Appear or by uploading a specification (manually, using CLI, or CI)

• Branches can be forked from any environment or other branch

• Branches can be merged to other branches by applying their diff

• Branches can be linked to an environment. This automatically applies changes and helps detect inconsistencies. For example, this is useful for linking main branch with production environment

Use Cases

Deployment Safety: Use diffs between branches and environments to answer questions like “Can I deploy to production?” by detecting breaking changes before they occur.

Example: compare feature branch with production environment to validate the feature branch won't cause breaking change.

API Consistency (planned): Use branches attached to environments to identify inconsistencies between API specifications and live implementations.

Example: link main branch with production and receive notification when service responds with data not matching contracts.

Change Communication (planned): Use diffs to describe changes to your API and share automatically generated changelog to your consumers.

Example: automatically share API changes to your Slack channel so people know what's coming up