Appear docs
HomepageGitHubAPI toolkitSign inGet demo
  • Getting Started
    • Welcome to Appear
    • How Appear works
    • Who is Appear for?
    • Get In Touch
    • Installation
  • Installation
    • Javascript / Typescript
    • Framework specific installations
      • NestJS
      • NextJS
      • Custom integrations
  • Explanations
    • Branches and environments
  • Connections
  • Managing your APIs
    • Creating a service
    • Add service via URL
    • Grouping & filtering
    • Editing your APIs
    • Overriding/updating a service
  • OpenAPI spec version
  • Tagging services
  • Service Resources
    • Resource map
  • Managing your organisation
    • Managing team members
    • Adding verified domains
  • Resources
    • FAQs
    • Product Map
    • Open-source
Powered by GitBook
On this page
  • Overview
  • Shared aspects:
  • Environments
  • Branches
  • Use Cases

Was this helpful?

  1. Explanations

Branches and environments

Learn about how branches and environments work in Appear.

PreviousCustom integrationsNextConnections

Last updated 18 days ago

Was this helpful?

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.

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


If you have any queries or require support with the above instructions, please with us.

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