krzko / restmigrate

Restmigrate is a tool for managing REST API configuration migrations, inspired by database schema migration tools.

restmigrate

restmigrate is a Go-based tool for managing and applying configuration changes to REST APIs in a systematic, version-controlled manner. It uses a migration-like approach similar to database schema migrations, allowing you to define, apply, and revert changes to your REST API configurations.

Features

• Create, apply, and revert REST API configuration changes
• Support for multiple API gateways or generic API endpoints (e.g., Kong, APISIX, Generic)
• CUE language for defining migrations
• OpenTelemetry traces integration for observability

OpenTelemetry

restmigrate supports OpenTelemetry for distributed tracing, follow the configuration section to enable it.

Installation

brew

Install brew and then run:

brew install krzko/tap/restmigrate

Download Binary

Download the latest version from the Releases page.

Commands

• create: Create a new migration file
• up: Apply pending migrations
• down: Revert the last applied migration (use --all to revert all)
• list: Display applied migrations

Configuration

Set these environment variables to configure restmigrate:

• OTEL_EXPORTER_OTLP_ENDPOINT: OpenTelemetry exporter endpoint
• OTEL_EXPORTER_OTLP_INSECURE: Set to "true" for insecure connection
• OTEL_SDK_ENABLED: Set to "true" to enable OpenTelemetry (disabled by default)

Usage

Creating a new migration

To create a new migration file:

restmigrate create <migration_name>

This will create a new CUE file in the migrations directory with a timestamp prefix.

Applying migrations

To apply all pending migrations, --token and --type are optional if the API does not require authentication:

restmigrate up --url <api_base_url> --token <api_token> --type <type>

Reverting the last migration

To revert the most recently applied migration:

restmigrate down --url <api_base_url> --token <api_token> --type <type>

Migration File Format

Migration files are written in CUE and should follow this structure:

migration: {
    timestamp: 1625097600  // Unix timestamp
    name:      "add_new_endpoint"
    up: {
        "/api/v1/new_endpoint": {
            method: "POST"
            body: {
                // Define the request body here
            }
        }
    }
    down: {
        "/api/v1/new_endpoint": {
            method: "DELETE"
        }
    }
}

The up and down fields define the changes to be applied and reverted, respectively. The timestamp field is used to track the order of migrations.

Examples of migration files can be found in the examples directory.

Development

To set up the development environment:

1. Clone the repository:

git clone https://github.com/krzo/restmigrate.git

2. Change to the project directory:

cd restmigrate

3. Install dependencies:

go mod tidy

4. Build the project:

make build