requestmigrations

package module
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Jan 16, 2024 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, "createUser")
  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, "createUser")
  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 MigrationStore) (*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)
}

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

type MigrationStore added in v0.4.0

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

type Migrations

type Migrations []Migration

Migrations is an array of migrations declared by each handler.

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 MigrationStore) error

func (*RequestMigration) VersionRequest added in v0.3.0

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

func (*RequestMigration) VersionResponse added in v0.3.0

func (rm *RequestMigration) VersionResponse(r *http.Request, body []byte, handler string) ([]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