<!--
title: Preserve API Contracts
domain: devtools
topic: API
language: Other
source: mermaid-js/mermaid
updated: 2025-05-23
url: https://awesomereviewers.com/reviewers/mermaid-preserve-api-contracts/
-->

When an endpoint or syntax is already used as a contract (e.g., chart grammar shared across features, or a stateful editor URL), avoid creating parallel interfaces or polluting the contract with unrelated concerns.

Apply this as:
- Prefer extending an existing syntax/API instead of adding a separate, parallel one (reduces duplication and client/parser divergence).
- If a URL encodes application state, keep the URL’s state-related parameters clean; don’t add marketing/tracking query params to the same URL the app uses to store/load state.

Example (clean stateful editor URL):
```ts
// Bad: pollutes a stateful URL used by the editor
const liveUrl =
  'https://mermaid.live/edit?utm_source=mermaid_js&utm_medium=editor_selection&utm_campaign=open_source';

// Good: keep only the contract URL; send analytics separately
const liveUrl = 'https://mermaid.live/edit';
```
