requestmigrations

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Dec 23, 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.
  • Support arbitrary data migration. (Coming soon)

Installation

 $ go get github.com/subomi/requestmigrations 

Usage

This package primarily exposes two APIs - VersionRequest and VersionResponse used in your HTTP handlers to transform the request and response respectively. Here's an short example:

package main 

func createUser(r *http.Request, w http.ResponseWriter) {
    err := rm.VersionRequest(r)
	if err != nil {
		t.Fatal(err)
	}

	payload, err := io.ReadAll(r.Body)
	if err != nil {
		t.Fatal(err)
	}

	var userObject user
	err = json.Unmarshal(payload, &userObject)
	if err != nil {
		t.Fatal(err)
	}

	userObject = user{
		Email:     userObject.Email,
		FirstName: userObject.FirstName,
		LastName:  userObject.LastName,
	}

	body, err := json.Marshal(userObject)
	if err != nil {
		t.Fatal(err)
	}

    resBody, err := rm.VersionResponse(r, body)
	if err != nil {
		t.Fatal(err)
	}

	_, _ = w.Write(resBody)
}

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")
	ErrCurrentVersionCannotBeEmpty = errors.New("Current Version field cannot be empty")
)

Functions

func Newmigrator added in v0.3.0

func Newmigrator(from, to *Version, avs []*Version, migrations Migrations) (*migrator, error)

Types

type GetUserVersionFunc added in v0.3.0

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

type Migration

type Migration interface {
	Migrate(data []byte, header http.Header) ([]byte, http.Header, error)
	ShouldMigrateConstraint(url *url.URL, method string, data []byte, isReq bool) bool
}

Migration is the core interface each transformation in every version needs to implement. It includes two predicate functions and two transformation functions.

type Migrations

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

type RequestMigration

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

RequestMigration is the exported type responsible for handling request migrations.

func NewRequestMigration

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

func (*RequestMigration) RegisterMetrics added in v0.3.0

func (rm *RequestMigration) RegisterMetrics(reg *prometheus.Registry)

func (*RequestMigration) RegisterMigrations

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

func (*RequestMigration) VersionRequest added in v0.3.0

func (rm *RequestMigration) VersionRequest(r *http.Request) error

func (*RequestMigration) VersionResponse added in v0.3.0

func (rm *RequestMigration) VersionResponse(r *http.Request, body []byte) ([]byte, error)

type RequestMigrationOptions

type RequestMigrationOptions struct {
	// VersionHeader refers to the header value used to retrieve the request's
	// version. If VersionHeader is empty, we call the GetUserVersionFunc to
	// retrive the user's version.
	VersionHeader string

	// CurrentVersion refers to the API's most recent version. This value should
	// map to the most recent version in the Migrations slice.
	CurrentVersion string

	// GetUserHeaderFunc is a function to retrieve the user's version. This is useful
	// where the user has a persistent version that necessarily being available in the
	// request.
	GetUserVersionFunc GetUserVersionFunc

	// VersionFormat is used to specify the versioning format. The two supported types
	// are DateFormat and SemverFormat.
	VersionFormat VersionFormat
}

RequestMigrationOptions is used to configure the RequestMigration type.

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