API Contract Monitoring

What is API contract monitoring?

API contract monitoring goes beyond status code checks. It validates that the shape and types of your API responses match an expected schema. This catches breaking changes — like a renamed field, a missing property, or a changed data type — that would cause downstream consumers to fail even when the endpoint returns 200 OK.

Defining an expected schema

When creating or editing an HTTP monitor, navigate to the Contract Validation section.

Define your expected schema as a JSON object where each key maps to a field type:

{
  "id": "string",
  "name": "string",
  "price": "number",
  "active": "boolean",
  "tags": "array",
  "metadata": "object"
}

Supported field types

Required vs optional fields

By default, all fields in the schema are required — if a field is missing from the response, it’s flagged as a violation. To mark a field as optional, suffix the type with ?:

{
  "id": "string",
  "name": "string",
  "description": "string?",
  "metadata": "object?"
}

In this example, id and name must always be present, while description and metadata may be absent without triggering a violation.

Nested objects

For APIs with nested structures, define the expected shape recursively:

{
  "user": {
    "id": "string",
    "email": "string",
    "profile": {
      "display_name": "string",
      "avatar_url": "string?"
    }
  },
  "permissions": "array"
}

Signalog validates each level of nesting independently. If user.profile is present but missing display_name, that specific violation is reported with the full path (e.g., user.profile.display_name is missing).

Viewing violations

When a contract violation is detected, it appears in two places:

1. Check result detail — Each check that fails contract validation shows a list of violations with the field path, expected type, and actual value received.
2. Monitor detail page — A “Contract Violations” tab shows a timeline of violations, making it easy to spot when a breaking change was deployed.

Contract violations do not automatically change the monitor state to Down (the HTTP check can still pass). However, you can configure the monitor to treat contract violations as failures under Monitor Settings > Contract Validation > Treat violations as failures.

Example use case

Imagine you expose a REST API consumed by a mobile app. A backend deploy renames user_name to username. The endpoint still returns 200, health checks pass, but the mobile app crashes trying to read user_name.

With contract monitoring, Signalog detects the missing user_name field immediately and alerts you before users are affected.

Next steps

• Set up synthetic multi-step checks for complex API workflows
• Track deployments to correlate contract violations with releases