Skip to main content

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:

  • Identify differences between service instances
  • Promote desired changes with precision
  • Maintain consistency across environments

How this works​

To compare two services, you evaluate the target service against a source service. This can be done via API or CLI. The response will show a diff—a list of changes between the two configurations.

{
  "diff": [
    {
      "operation": "replace",
      "path": "/dimensions/environment",
      "source_value": "production",
      "target_value": "staging"
    }
  ],
}

The operations returned in the diff can be:

  • replace
  • add
  • remove

These indicate how the target service differs from the source.

What can be compared?

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

How to compare services​

You can initiate a service comparison using either the API or CLI:

np service compare create \
  --id 9d4f2c8e-7b7e-4d52-9d60-1f8be94d7e7f \
  --body '{"source_service_id": "b3c81eaf-2e2c-4cb4-a907-5b58e8df3f4d"}' \
  --query .diff
Filter the response using the CLI

Use the --query .diff flag to return only the list of differences.

Interpreting the output​

Here’s an example diff output:

{
  "diff": [
    {
      "operation": "replace",
      "path": "/attributes/endpoints/2/path",
      "source_value": "/api/v1/users",
      "target_value": "/api/v1/user"
    }
  ],
}

This means that the path at endpoint index 2 differs between the services. In this case, the comparison suggests replacing /api/v1/user with /api/v1/users.

Use case: API Gateway service​

Imagine you manage an API Gateway service that defines endpoint paths. You can use the comparison tool to:

  • Ensure routing rules are consistent across environments
  • Detect path mismatches or missing endpoints
  • Confidently promote accurate configurations

By running a service comparison, discrepancies like this are surfaced and can be acted upon quickly.

Customizing comparisons​

Sometimes, certain fields differ by design between environments—such as account IDs, timestamps, or region-specific attributes. To avoid noisy diffs, you can mark these attributes 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
      }
    }
  }
}

These attributes will be excluded from the diff output, allowing you to focus on meaningful changes only. See Special schema keys for more info.