Compare services across environments

Overview

When working across multiple environments—such as development, staging, and production—it’s essential to keep service configurations in sync. Nullplatform provides a service comparison feature that helps you:

• Spot differences between service instances
• Promote changes with confidence
• Keep environments aligned

How this works

To compare two services, you select a target service and compare it against a source service. You can do this via the API or CLI. The response will include a diff, which is a list of JSON Patches showing how the target differs from the source.

{
  "diff": [
    {
      "op": "replace",
      "path": "/dimensions/environment",
      "value": "staging"
    }
  ]
  "source": {...},    // The source service instance
  "target": {...}    // The target service instance
}

Understanding the diff output

Each item in the diff array describes a change needed to make the source service match the target.

Operation	What it means	What you need to do
add	A value is in the target but missing in the source.	Add the value to the source.
replace	The value exists in both, but they differ.	Update the source to match the target.
remove	The value is in the source but not in the target.	Remove it from the source.
move	A value needs to be relocated. Includes a from path.	Move the value from one path to another in the source.

Other fields:

• path: A JSON Pointer that tells you where the operation should happen in the source.
• from: Required for move operations. Specifies the original JSON Pointer of the value being moved
• value: The new value to add or replace. Not present in remove or move operations.

These operations aren’t applied automatically—they’re suggestions for how to align the two services. You can apply them manually or use them as part of your promotion process.

What can be compared?

Only services with the same specification structure can be compared (for example, two SQS Queue services or two MySQL services).

How to compare services

You can start a comparison using either the API or the CLI:

CLI

np service compare create \
  --id <target_service_id> \
  --body '{"source_service_id": "<source_service_id>"}' \
  --query .diff

cURL

curl -L 'https://api.nullplatform.com/service/<target_service_id>/compare' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "source_service_id": "<source_service_id>"
}'

Filter the response using the CLI

Use the --query .diff flag to return just the list of JSON Patches.

Use case: API Gateway service

Let’s say you manage an API Gateway service that defines endpoint paths. You can use the comparison tool to:

• Check if routing rules are consistent across environments
• Catch mismatches or missing endpoints
• Confidently promote accurate configurations

By running a service comparison, you can quickly surface these kinds of differences and take action before they cause issues.

Customizing comparisons

Sometimes, certain fields vary between environments on purpose—like account IDs, timestamps, or region-specific values. To avoid cluttering the diff with these kinds of differences, you can mark fields as non-comparable in your service specification using the comparable: false flag.

Example:

{
  "attributes": {
    "schema": {
      "account_id": {
        "type": "string",
        "config": {
          "key": "aws.account_id"
        },
        "export": false,
        "readOnly": true,
        "comparable": false
      }
    }
  }
}

Any attribute marked this way will be ignored in the diff, so you can focus on the changes that really matter. See Special schema keys for more info.