apidiff

README

API Diff

Records HTTP API (JSON based) calls and compares the them on both HTTP and JSON level. This is helpful when migrating or refactoring APIs to make sure your API contract did not change. It also stores basic performance metrics.

Installation

$ go get github.com/tgrk/apidiff

Usage

$ apidiff -h
Usage: apidiff [OPTIONS] argument ...

  -compare
    	compare recorded sessions against a URL
  -del
    	list all recorded API sessions
  -detail
    	view detail fo recorded API session
  -dir string
    	path where API calls are stored (default $HOME/.apidiff/)
  -list
    	list all recorded API sessions
  -name string
    	name of session to be recorded
  -record
    	record a new API session
  -show
    	list all recorded API sessions
  -v	prints current program version
  -verbose
    	output basic progress

Record a new session

Reads manifest file from both CLI arguments and STDIN:

appidiff -record -name "foo" examples/simple.yaml

$ cat examples/simple.yaml | ./appidiff -record -name "foo"

List all existing sessions

appidiff -list

Show an existing session

appidiff -show "foo"

Detail of first session interaction

appidiff -detail "foo" 1

Delete an existing session

appidiff -del "foo"

Compare against an existing sessions

Compare existing session against a manifest with other API:

appidiff -compare -name "bar" examples/simple.yaml

Documentation

Index

• type APIDiff
  • func New(path string, options Options) *APIDiff
  • func (ad *APIDiff) Compare(source RecordedSession, target Manifest) (map[int]Differences, error)
  • func (ad *APIDiff) Delete(name string) error
  • func (ad *APIDiff) Detail(name string, interactionIndex int) (*cassette.Interaction, *RequestStats, error)
  • func (ad *APIDiff) List() ([]RecordedSession, error)
  • func (ad *APIDiff) Record(dir, name string, interaction RequestInteraction, ri RequestInfo, ...) error
  • func (ad *APIDiff) Show(name string) (RecordedSession, error)
• type Differences
• type Manifest
  • func NewManifest() *Manifest
  • func (m *Manifest) Parse(r io.Reader) error
• type MatchingRules
• type Options
• type RecordedInteraction
• type RecordedSession
• type RequestInfo
• type RequestInteraction
  • func (ri RequestInteraction) Fingerprint() string
• type RequestStats
  • func (rs RequestStats) Duration() int
• type UI
  • func NewUI(w io.Writer) *UI
  • func (ui *UI) ListSessions(sessions []RecordedSession, showCaption bool)
  • func (ui *UI) ShowComparisonResults(source RecordedSession, errors map[int]Differences)
  • func (ui *UI) ShowInteractionDetail(interaction *cassette.Interaction, stats *RequestStats)
  • func (ui *UI) ShowSession(session RecordedSession)

Types

type APIDiff

type APIDiff struct {
	DirectoryPath string
	Options       Options
}

APIDiff instance

func New

func New(path string, options Options) *APIDiff

New creates a new instance

func (*APIDiff) Compare

func (ad *APIDiff) Compare(source RecordedSession, target Manifest) (map[int]Differences, error)

Compare compare stored session against a manifest

func (*APIDiff) Delete

func (ad *APIDiff) Delete(name string) error

Delete an existing recorded session; otherwise returns error

func (*APIDiff) Detail

func (ad *APIDiff) Detail(name string, interactionIndex int) (*cassette.Interaction, *RequestStats, error)

Detail returns interaction from recorded session given its name and index

func (*APIDiff) List

func (ad *APIDiff) List() ([]RecordedSession, error)

List existing stored API recording sessions

func (*APIDiff) Record

func (ad *APIDiff) Record(dir, name string, interaction RequestInteraction, ri RequestInfo, rules []MatchingRules) error

Record stores requested URL using casettes into a defined directory

func (*APIDiff) Show

func (ad *APIDiff) Show(name string) (RecordedSession, error)

Show returns an existing recorded session otherwise an error

type Differences

type Differences struct {
	URL              string
	InteractionIndex int
	Headers          map[string]error
	Body             map[string]error
	Changed          bool
}

Differences represents errors between two interactions

type Manifest

type Manifest struct {
	Version       int                  `yaml:"version"`
	MatchingRules []MatchingRules      `yaml:"matching_rules"`
	Request       RequestInfo          `yaml:"request"`
	Interactions  []RequestInteraction `yaml:"interactions"`
}

Manifest holds all information needed for running requests against API

func NewManifest

func NewManifest() *Manifest

NewManifest creates an empty manifest

func (*Manifest) Parse

func (m *Manifest) Parse(r io.Reader) error

Parse YAML document

type MatchingRules

type MatchingRules struct {
	Name  string      `yaml:"name"`
	Value interface{} `yaml:"value"`
}

MatchingRules contains filter to be applied to stored interactions

type Options

type Options struct {
	Verbose bool
	Name    string
}

Options holds shared CLI arguments from user

type RecordedInteraction

type RecordedInteraction struct {
	URL        string
	Method     string
	StatusCode int
	Stats      RequestStats
}

RecordedInteraction represents recorded API interaction

type RecordedSession

type RecordedSession struct {
	Name         string
	Path         string
	Interactions []RecordedInteraction
	Created      time.Time
}

RecordedSession represents stored API session

type RequestInfo

type RequestInfo struct {
	Payload string      `yaml:"body"`
	Headers http.Header `yaml:"headers"`
}

RequestInfo contains shared API request details

type RequestInteraction

type RequestInteraction struct {
	URL        string      `yaml:"url"`
	Method     string      `yaml:"method"`
	StatusCode int         `yaml:"status_code"`
	Headers    http.Header `yaml:"headers"`
	Payload    string      `yaml:"body"`
}

RequestInteraction represents request info for API interaction

func (RequestInteraction) Fingerprint

func (ri RequestInteraction) Fingerprint() string

Fingerprint returns unique signature of request that is used for later comparison

type RequestStats

type RequestStats struct {
	DNSLookup        int `yaml:"dns_lookup"`
	TCPConnection    int `yaml:"tcp_connection"`
	TLSHandshake     int `yaml:"tls_andshake"`
	ServerProcessing int `yaml:"server_processing"`
	ContentTransfer  int `yaml:"content_transfer"`
}

RequestStats hold HTTP stats metrics

func (RequestStats) Duration

func (rs RequestStats) Duration() int

Duration returns total time spend on request

type UI

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

UI contains helpers for drawing CLI interface

func NewUI

func NewUI(w io.Writer) *UI

NewUI returns instance

func (*UI) ListSessions

func (ui *UI) ListSessions(sessions []RecordedSession, showCaption bool)

ListSessions draws table of existing recorded sessions

func (*UI) ShowComparisonResults

func (ui *UI) ShowComparisonResults(source RecordedSession, errors map[int]Differences)

ShowComparisonResults displays result of comparing source and target sessions

func (*UI) ShowInteractionDetail

func (ui *UI) ShowInteractionDetail(interaction *cassette.Interaction, stats *RequestStats)

ShowInteractionDetail displays recorded session interaction by given index

func (*UI) ShowSession

func (ui *UI) ShowSession(session RecordedSession)

ShowSession displays detail of selected session