requestmigrations

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 15, 2023 License: MIT Imports: 11 Imported by: 2

README

requestmigrations
Go Reference

requestmigrations is a Golang implementation of rolling versions for REST APIs. It's a port of the Ruby implementation by ezekg.

Features

  • API Versioning with date and semver versioning support.
  • Prometheus Instrumentation to track and optimize slow transformations.
  • Progressive versioning support - roll out versioning to a subset of your users. (Coming soon)
  • Support arbitrary data migration. (Coming soon)

Installation

 $ go get github.com/subomi/requestmigrations 

Usage

This package primarily exposes one API - VersionAPI. It can be used as an HTTP middleware to intercept and apply transformations on requests and responses to your REST API. See an abridged example below:

package main

func main() {
    rms := rm.NewRequestMigration(opts)

    r := mux.NewRouter()
    r.use(rms.VersionAPI)

    r.HandleFunc("/users", ListUsers).Methods("GET")
}

You can also use it to apply transformations to specific routes only. See example below:

package main

func main() {
    rms := rm.NewRequestMigration(opts)

    r := mux.NewRouter()
    r.HandleFunc("/users", rms.VersionAPI(ListUsers)).Methods("GET")
}

You can see a full example in the example directory for a detailed example.

Limitations

Please be advised that this package relies on httptest.ResponseRecorder, which, initially, was designed for your test environment rather than regular production code. I used the ResponseRecorder because wrapping http.ResponseWriter is weirdly not easy (you can read more here), and I was able to prototype the functionality of this package with the response recorder very quickly. However, from Go 1.20+, the go team introduced http.ResponseController (see #54136), making wrapping the response writer type easy. In subsequent releases, I will be wrapping the writer and removing the use of the response recorder type.

License

MIT License

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrServerError          = errors.New("Server error")
	ErrInvalidVersion       = errors.New("Invalid version number")
	ErrInvalidVersionFormat = errors.New("Invalid version format")
)

Functions

This section is empty.

Types

type GetUserHeaderFunc

type GetUserHeaderFunc func(req *http.Request) (string, error)

type Migration

type Migration interface {
	ShouldMigrateRequest(req *http.Request) bool
	MigrateRequest(req *http.Request) error

	ShouldMigrateResponse(req *http.Request, res *http.Response) bool
	MigrateResponse(res *http.Response) error
}

Migration is the core interface each transformation in every version needs to implement.

type Migrations

type Migrations map[string][]Migration
migrations := Migrations{
  "2023-02-28": []Migration{
    Migration{},
	   Migration{},
	 },
}

type Migrator

type Migrator struct {
	// contains filtered or unexported fields
}

func NewMigrator

func NewMigrator(from, to *Version, avs []*Version, migrations Migrations) (*Migrator, error)

type RequestMigration

type RequestMigration struct {
	Metric *prometheus.HistogramVec
	// contains filtered or unexported fields
}

func NewRequestMigration

func NewRequestMigration(opts *RequestMigrationOptions) (*RequestMigration, error)

func (*RequestMigration) RegisterMigrations

func (rm *RequestMigration) RegisterMigrations(migrations Migrations) error

func (*RequestMigration) VersionAPI

func (rm *RequestMigration) VersionAPI(next http.Handler) http.Handler

type RequestMigrationOptions

type RequestMigrationOptions struct {
	VersionHeader     string
	CurrentVersion    string
	GetUserHeaderFunc GetUserHeaderFunc
	VersionFormat     VersionFormat
}

type Version

type Version struct {
	Format VersionFormat
	Value  interface{}
}

func (*Version) Equal

func (v *Version) Equal(vv *Version) bool

func (*Version) IsValid

func (v *Version) IsValid() bool

func (*Version) String

func (v *Version) String() string

type VersionFormat

type VersionFormat string
const (
	SemverFormat VersionFormat = "semver"
	DateFormat   VersionFormat = "date"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL