Api-Breaking-Change-Detector

# API Breaking Change Detector

You are cross-referencing a C# Web API's actual contract (controllers, DTOs, route definitions) against its TypeScript/JavaScript consumers to find contract drift — in both directions — before it reaches production.

When to use this

Trigger when the user asks to:

- Check whether a DTO/controller change will break frontend or client applications

- Verify the client and backend API contract are still in sync

- Audit a specific endpoint, or the whole API surface, for breaking changes before a release

Do not use this for:

- Generating new API code from an OpenAPI spec (see `openapi-to-application-code`)

- Scaffolding new endpoints with OpenAPI docs (see `aspnet-minimal-api-openapi`)

- Comparing two OpenAPI spec *files* directly — this skill reads source code, not exported specs

Process

1. **Discover Global JSON & Naming Policies:**

- Check `Program.cs` or `Startup.cs` for active JSON options (e.g. `JsonNamingPolicy.CamelCase`, `PropertyNamingPolicy`, or Newtonsoft `CamelCasePropertyNamesContractResolver`).

- Default to `camelCase` for TypeScript/JavaScript field mapping if global camelCase is configured, unless overridden by an explicit `[JsonPropertyName("...")]` attribute on the C# property.

- Ignore C# properties annotated with `[JsonIgnore]`.

2. **Identify the C# contract surface.** For each Controller action in scope:

- **Route**: Base `[Route("...")]` + action `[HttpGet("...")]` / `[HttpPost("...")]`. Normalize route parameters (e.g. `{id:int}` or `{id:guid}` $\rightarrow$ `{id}`).

- **Request DTO**: Extract property names, types, and requirement rules:

- *Required if*: annotated with `[Required]`, `[BindRequired]`, has the C# 11 `required` modifier (`public required string X`), or is a non-nullable value type (`int`, `Guid`, `bool`) without a default value.

- *Optional if*: nullable (`string?`, `int?`), or has a default initializer.

- **Response DTO**: Property names, types, and nullability.

- **Explicit Status Codes**: `[ProducesResponseType(statusCode)]` attributes and explicit `StatusCode(...)` return paths.

3. **Find the matching TypeScript/JavaScript consumer (with Normalized URL Matching):**

- **Auto-generated client match (high confidence):** look for generated client files (NSwag/OpenAPI Generator output) and match by generated method/interface name directly.

- **Hand-written service/client match (medium confidence):**

- Search TypeScript/JavaScript files for HTTP client calls (`fetch`, `axios`, Angular `HttpClient`, `ky`, etc.) whose normalized URL pattern matches the controller's route.

- Normalize template strings and concatenations (e.g., `${this.apiUrl}/users/${id}` or `baseUrl + '/users/' + userId` $\rightarrow$ `/users/{id}`).

- Match normalized routes against C# routes regardless of variable naming in TypeScript/JS.

- **No match found:** report as "no client consumer located" rather than guessing — do not assume an endpoint is unused just because a match wasn't found statically.

- Label every finding with which of these three methods was used to locate it.

4. **Compare backend → frontend/client (breaks the client):**

- A DTO property renamed or removed that the TypeScript/JS interface or object model still expects

- A new required request field the client never sends

- A response status code the client doesn't handle (e.g. controller now returns 409 Conflict, but client error handler only handles 400/500)

- A response field's type changed (e.g. `long` $\rightarrow$ `string`, or non-nullable $\rightarrow$ nullable) in a way the client type assumes differently

5. **Compare frontend/client → backend (stale/dead client code vs. silent bugs):**

- *Harmless dead field*: Client sends a payload property the backend ignores without error.

- *Silently broken bug (High Severity)*: Client logic reads a response property that the backend no longer returns (resulting in `undefined` at runtime and pot