Why APIs change (and why you should care)
APIs are software, and software evolves. Even well-maintained APIs with versioning policies introduce changes that can affect your integration. New fields appear in responses. Deprecated fields stop being populated. Pagination behavior shifts. Error response formats change. Authentication requirements get updated.
The problem is not change itself. It is undetected change. When a third-party API modifies its response schema, the impact on your application depends on how you parse that response. If you are accessing a field that no longer exists, your code throws an error. If a field changes from a string to an array, your type assumptions break. If a new required authentication header is enforced, all your requests start failing.
Most teams discover these changes the hard way: a user reports a bug, an error rate spikes in production, or a data pipeline starts producing garbage output. API monitoring shifts this from reactive debugging to proactive detection, giving you hours or days of lead time to adapt.
Setting up API endpoint monitoring
Monitoring an API endpoint is conceptually similar to monitoring a web page. You make a request at regular intervals, store the response, and compare it to the previous version. The differences lie in how you make the request and how you compare the responses.
To set up an API monitor in OnChange, provide the endpoint URL and configure it for JSON response monitoring. Unlike web page monitoring, API monitoring skips the browser rendering step and makes a direct HTTP request, which is faster and more reliable for structured data endpoints.
Configuring custom headers and authentication
Most APIs require authentication. Your monitoring setup needs to include the same headers your application uses to access the API. Common authentication patterns include:
- --API key headers -- Add a custom header like
X-API-Key: your-keyorAuthorization: ApiKey your-key. This is the most common pattern for public APIs. - --Bearer tokens -- Set the
Authorization: Bearer your-tokenheader. For OAuth-based APIs, you may need to periodically refresh the token and update your monitor configuration. - --Content-Type headers -- Some APIs return different formats based on the Accept header. Set
Accept: application/jsonto ensure you receive JSON responses consistently. - --Query parameters -- For APIs that use key-based authentication in the URL, append the key as a query parameter. OnChange treats the full URL including query parameters as the endpoint identifier.
Store API keys securely. OnChange encrypts all custom headers at rest and in transit. Never hardcode production API keys in shared configurations. If possible, create a dedicated read-only API key specifically for monitoring purposes, separate from the keys your application uses.
Understanding JSON diff detection
JSON diff detection is fundamentally different from text diff detection. When comparing two JSON responses, a naive text-based comparison would flag whitespace changes, key reordering, and formatting differences as meaningful changes. A proper JSON diff engine understands the structure of the data and compares it semantically.
OnChange's JSON comparison handles these nuances automatically. It normalizes key ordering so that two objects with the same keys in different orders are treated as identical. It ignores insignificant whitespace. And it produces a structured diff that tells you exactly which fields were added, removed, or modified, along with their old and new values.
Types of API changes to watch for
Not all API changes carry the same risk. Understanding the categories helps you prioritize your response:
- --Field additions -- New fields appear in the response. These are usually backward-compatible and low risk, but they may indicate upcoming features or deprecation of existing fields.
- --Field removals -- Existing fields disappear. This is a breaking change if your code depends on those fields. Requires immediate attention.
- --Type changes -- A field changes from a string to a number, from a single value to an array, or from an object to null. These break type assumptions in your parsing code and are high-severity.
- --Value changes -- The structure stays the same, but specific values change. This is the normal behavior for data endpoints and is only significant if you are tracking specific data points.
- --Status code changes -- The endpoint starts returning 403, 429, or 500 instead of 200. This signals authentication issues, rate limiting, or server problems.
Configuring webhook alerts for API changes
When an API change is detected, you need to know about it through channels that fit your workflow. OnChange supports multiple notification channels including email, Slack, Discord, and custom webhooks.
Custom webhooks are particularly valuable for API monitoring because they let you trigger automated responses. When OnChange detects a schema change in a third-party API, a webhook can automatically create an issue in your project tracker, post to your engineering team's Slack channel, or trigger a CI pipeline that runs your integration tests against the new schema. Check our integrations page for the full list of supported notification channels.
The webhook payload includes the full diff between the previous and current responses, the timestamp of the change, the HTTP status code, and response headers. This gives your downstream systems enough context to make intelligent decisions about how to handle the change.
Common API monitoring patterns
Different teams monitor APIs for different reasons. Here are the most common patterns we see across OnChange users:
Third-party integration monitoring
If your product integrates with external APIs like payment processors, shipping providers, or data vendors, monitor the endpoints you depend on. Focus on the specific API routes your code calls, not the entire API surface. Track response schemas to catch breaking changes, and monitor status codes to detect outages or authentication failures before your users do.
Public API data tracking
Many teams monitor public APIs to track market data, government datasets, financial feeds, or competitor product catalogs exposed via API. For these use cases, value changes are the primary signal rather than schema changes. Set up monitors on specific data endpoints and use the change history to build a time-series view of the data over weeks and months.
Internal API regression detection
Use API monitoring on your own endpoints as a lightweight contract testing layer. Monitor your staging or production API responses to detect unintended schema changes before customers report bugs. This complements your existing test suite by catching changes that occur due to database migrations, dependency updates, or configuration changes that bypass your unit tests.
Best practices for API monitoring
After working with teams across industries, we have identified several practices that separate effective API monitoring from noisy, unreliable setups:
- --Use dedicated API keys. Create separate API keys for monitoring so you can revoke them independently and track rate limit consumption separately from your production traffic.
- --Monitor both schema and status. Schema changes tell you the response structure has evolved. Status code changes tell you the endpoint is having problems. Both require different responses but are equally important.
- --Check response headers too. API version numbers, deprecation warnings, and rate limit status often appear in response headers. Monitoring just the body misses these early warning signals.
- --Respect rate limits. Set your monitoring interval to stay well within the API's rate limits. A check every 5 to 15 minutes is sufficient for most integration monitoring. High-frequency polling wastes your quota and may get your monitoring key blocked.
Getting started with API monitoring
Start by listing the third-party APIs your product depends on. Identify the specific endpoints your code calls and create a monitor for each one. Configure authentication headers, set a reasonable check interval, and route alerts to your engineering team's Slack channel or email.
For a broader view of website and content monitoring strategies, read our website monitoring best practices guide. If you are also tracking competitor web pages alongside their APIs, our competitor price tracking guide covers the web-scraping side of competitive intelligence.
OnChange makes API monitoring straightforward. Create a free account, add your first endpoint, configure your headers, and you will receive your first change alert within minutes. Get started for free.