Description + Example

TL;DR: Utility to aid in the migration of endpoints (especially useful for cloud migrations) by hitting both the old and new service and comparing various properties.

This utility is aimed at ensuring parity between two (currently only supports GET) endpoints (and sets of endpoints). For each provided endpoint a request will be made of each of the defined services and properties about the request recorded such as:

• Status code
• Response time
• Response body

Using the above a 'report' can be generated in both HTML and JSON formats. The HTML report includes a diff between the two response bodies.

🛠 Installation

This utility is available on NPM! Simply run the following to get started:

npm install -g migrationbuddy

🚀 Usage

Note: Both migbuddy and migrationbuddy are available as commands and are identical in function.

• Generate a configuration file template/example

  migbuddy generate <path/to/write/file.json>

• Execute endpoint comparison

  migbuddy <path/to/config/file.json>

  Flags:

  • ohf, --output-html-file <path> [Optional] - Path to create output HTML file.
  • ojf, --output-json-file <path> [Optional] - Path to create output JSON file.
  • -oc, --output-to-clipboard [Optional, default false] - Copy the result JSON structure to the clipboard.
  • -v, --verbose [Optional, default false] - Enable verbose logging -- may help to identify errors.
  • For most up-to-date flags run migbuddy --help.

Configuration:

Top level configuration

Some configurations can / should be set at a global level, the following properties exist:

• endpoints - [See Endpoint Config] Configuration of the various endpoint to compare.
• configuration - [See Global Config] Properties defining the control and candidate services.

Endpoint Config

Note: Values set at the endpoint level such as headers and substitutions will override those set in the global context.

Each endpoint can optionally have the following properties:

• candidatePath: An alternate path to use for the candidate service. This is useful if the endpoint has changed slightly between services i.e. /api/v1/todos/{id} -> /api/v2/todos/{id}.
• substitutions: A JSON key value structure allowing for URL templating. Any matching instances of a variable in the path e.g. {key} will be replaced by a corresponding substitution value from the map.
• headers: A JSON key value structure allowing for headers to be provided at the endpoint level.
• options:
  • diff:
    • ignoreKeys: String array of keys to be ignored when performing the diff. Note: Specifying an empty array [] has special significance. It will prevent the global config for this property being merged for this endpoint.
    • sortArrays: Boolean value indicating if arrays should be sorted (recursively) when performing the diff.
    • sortBy: String array of keys to be used for comparing objects when sorting arrays. Note: Specifying an empty array [] has special significance. It will prevent the global config for this property being merged for this endpoint.

Global Config

• global:
  • substitutions: A JSON key value structure allowing for URL templating. Any matching instances of a variable in the path e.g. {key} will be replaced by a corresponding substitution value from the map.
  • headers: A JSON key value structure allowing for headers to be provided at the global (all endpoints) level.
  • options:
    • diff:
      • ignoreKeys: String array of keys to be ignored when performing the diff. Note: Specifying an empty array [] has special significance. It will prevent the global config for this property being merged for this endpoint.
      • sortArrays: Boolean value indicating if arrays should be sorted (recursively) when performing the diff.
      • sortBy: String array of keys to be used for comparing objects when sorting arrays. Note: Specifying an empty array [] has special significance. It will prevent the global config for this property being merged for this endpoint.
    • htmlReport:
      • theme: Specify either light or dark to choose the theme applied to the HTML report. (default light)
• control: The 'old' service that is being replaced (this may be the same as the candidate)
  • url: URL of the service
  • headers: A JSON key value structure allowing for headers to be provided at the only to the control service.
• candidate: The 'new' service that is being replaced (this may be the same as the control)
  • url: URL of the service
  • headers: A JSON key value structure allowing for headers to be provided at the only to the candidate service.

Example configuration

{
  "endpoints": {
    "/v1/todos/{id}": {
      "candidatePath": "/v2/todos/{id}",
      "substitutions": {
        "id": "john.doe"
      },
      "headers": {
        "X-SOME-HEADER": "HEADER_VALUE"
      },
      "options": {
        "diff": {
          "sortArrays": true,
          "ignoreKeys": ["_title"]
        }
      }
    }
  },
  "configuration": {
    "global": {
      "substitutions": {
        "id": "sally.woodworth"
      },
      "headers": {
        "X-SOME-GLOBAL-HEADER": "HEADER_VALUE"
      },
      "options": {
        "diff": {
          "sortArrays": true,
          "ignoreKeys": ["_links"]
        }
      }
    },
    "control": {
      "url": "https://my-old-api.tld/api",
      "headers": {
        "Authorization": "old-auth"
      }
    },
    "candidate": {
      "url": "https://my-new-api.tld/api",
      "headers": {
        "Authorization": "new-auth"
      }
    }
  }
}

Example report/output (JSON)

{
  "/v1/todos/{id}": {
    "status": {
      "pretty": "Control: 200 -> Candidate: 200",
      "control": 200,
      "candidate": 200
    },
    "responseTime": {
      "pretty": "Control: 158ms -> Candidate: 161ms (2% slower)",
      "control": 158,
      "candidate": 161,
      "metadata": {
        "unit": "milliseconds"
      }
    },
    "diff": {
      "title": {
        "__old": "Buy Milk",
        "__new": "Buy Eggs"
      }
    }
  }
}

Example report/output (HTML)

Author

👤 James McNee

• Website: https://www.jamesmcnee.com
• Github: @JamesMcNee

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 James McNee. This project is Unlicence licensed.

This README was generated with ❤️ by readme-md-generator