---
sidebar_label: Compare services
doc_id: 22bfb41a-1c12-444c-8aa8-ef2ccbe72cf0
description: >-
  Compare service configurations across environments to identify differences
  before syncing or deployment.
keywords:
  - service comparison
  - environment diff
  - JSON Patch
  - configuration management
  - deployment
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Compare services across environments

You can compare two service instances to see exactly how they differ. This is especially useful when reviewing changes
across environments, like from `development` to `staging`, or between region-specific deployments.

A comparison returns a structured `diff` using [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) format.
You’ll see which attributes were added, removed, or changed, and where.

This is often the first step before deciding to [sync](/docs/services/promote-service/sync-service) or
[create a new service](/docs/services/promote-service/create-service-from-service) based on an existing one.


## How this works

To compare two services, you select a **source** service and compare it against a **target** service. You can do this
using the [API](/docs/api/service-compare) or [CLI](/docs/cli/).

The response includes a `diff`, which is a list
of [JSON Patches](https://datatracker.ietf.org/doc/html/rfc6902) showing how the target differs from the source.


```json
{
  "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 array represents a change that would make the **source** 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](https://datatracker.ietf.org/doc/html/rfc6901) that tells you where the operation should
  happen in the source.
- **`from`**: Required for `move` operations. Specifies the original [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) 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.

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

## Run a comparison

You can start a comparison using either the [API](/docs/api/service-compare) or the [CLI](/docs/cli/):

<Tabs
defaultValue="service-compare-cli"
values={[
{ label: 'CLI', value: 'service-compare-cli' },
{ label: 'cURL', value: 'service-compare-curl' },
]}>
<TabItem value="service-compare-cli">

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

  </TabItem>
  <TabItem value="service-compare-curl">
```bash
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>"
}'
```
  </TabItem>
</Tabs>

:::tip Filter the response using the CLI
Use the `--query .diff` flag to return just the list of [JSON Patches](https://datatracker.ietf.org/doc/html/rfc6902).
:::

## Use case: API Gateway service

Let’s say you manage an API Gateway service that defines endpoint paths. You can compare the service across environments
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.