Why HTML Entities Show Up in API Responses
Debug escaped ampersands, quotes, angle brackets and double-encoded HTML entities that appear in JSON responses, rendered UI and copied API payloads.
Quick Answer
HTML entities appear in API responses when text was escaped for HTML before being stored or sent as JSON. Decode entities only at the correct rendering boundary, and check for double encoding such as & before changing API clients or database values.
Example Scenario
A JSON response contains company names like AT&T, descriptions with "quoted" words, or visible <strong> tags in the UI. The API is valid JSON, but a previous layer escaped content for HTML and another layer treats that escaped text as plain data.
Step-by-Step Explanation
- Identify whether the escaped text is inside JSON, HTML or a rendered UI.
- Check whether the value was escaped before storage, before API serialization or during rendering.
- Look for double encoding such as &amp; and &lt;.
- Decode only when the target context expects human-readable text.
- Avoid rendering decoded HTML as markup unless it is sanitized.
- Fix the boundary that performs escaping too early.
Escaping Depends on Context
HTML escaping is correct when text is inserted into an HTML document. It prevents characters such as < and & from being interpreted as markup. The same escaped text can be wrong inside a JSON API if clients expect the original human-readable value.
JSON has its own escaping rules. A string can safely contain ampersands and angle brackets without turning them into HTML entities. If the API returns AT&T as data, some earlier layer probably escaped for HTML before the JSON response was built.
The key question is not whether escaping is good or bad. The question is whether escaping happened at the right boundary for the current output context.
Double Encoding Is a Strong Clue
Values like &amp; and &lt; suggest text was escaped more than once. The first pass changed & into &. The second pass escaped the ampersand in that entity, making the entity visible to users.
Double encoding often appears when data is stored already escaped and then escaped again during rendering. It can also happen when a backend assumes a CMS field is raw text while the CMS already stored HTML-escaped text.
Decode one layer at a time during debugging. If decoding once produces another entity, you likely have a double-encoding path.
Storage Should Usually Keep Raw Text
For most application data, storing raw text is easier to reason about than storing HTML-escaped text. The output layer can escape for HTML, JSON, CSV or another format as needed. Escaping before storage locks the value to one context.
There are exceptions, such as storing sanitized rich HTML from a CMS. In that case the field should be clearly named and documented as HTML content, not plain text. Plain text fields and HTML fields should not be mixed casually.
If a database already contains escaped values, plan a migration carefully. Blindly decoding every value can create security issues if some fields intentionally store safe HTML.
Do Not Decode Into Unsafe Markup
Decoding <script> into <script> and then assigning it to innerHTML is dangerous. Entity decoding solves readability, not trust. If the decoded result is going to be rendered as markup, it needs sanitization and a clear content policy.
For plain UI text, render decoded content as textContent or through a frameworkâs normal text interpolation, not as raw HTML. That gives users readable text without turning it into executable markup.
Security and display bugs can look similar here. A visible <b> tag may be ugly, but decoding and rendering it as HTML can be worse if the source is not trusted.
API Contracts Should Name the Representation
If an API field contains plain text, clients should not need to HTML-decode it. If a field contains sanitized HTML, the field name and documentation should say so. Ambiguous fields force every client to guess.
A useful naming pattern is descriptionText for plain text and descriptionHtml for sanitized markup. That is not the only option, but it makes representation visible to client developers.
When clients disagree about whether to decode a field, the contract is under-specified. Fixing one client may break another unless the API representation is clarified.
Search and Indexing Can Amplify the Problem
Entity-escaped text can leak into search indexes, analytics events, emails and exports. Once that happens, fixing only the page renderer is not enough because downstream systems may already contain the escaped representation.
Check where the value travels after the API response. If the escaped form is stored in an index or sent to a third-party system, schedule a cleanup or reindex after fixing the source boundary.
For public content, escaped text also looks low quality to users because visible entities feel like broken formatting. That makes this both a data correctness issue and a content presentation issue.
What to Check Next
Use the HTML Entity Encoder/Decoder to inspect small examples and identify single versus double encoding. Then trace where the first escaped value was produced.
Compare the database value, API response and rendered UI. Seeing all three together usually reveals whether escaping happened during storage, serialization or rendering.
After the fix, add examples with ampersands, quotes and angle brackets. These characters catch most accidental context-mixing bugs.
Add one example that should remain visible as text, such as a company name with an ampersand, and one example that should never become executable markup. Testing both cases prevents a display fix from becoming a security regression.
If a migration is needed, sample existing records before decoding in bulk. Mixed raw and escaped data can exist in the same table after years of imports and editor changes.
Add monitoring for newly created escaped values after the fix. If fresh records still contain & or < in plain text fields, the source boundary is not fixed yet. A one-time cleanup without source prevention only makes the problem return quietly. Review imports, editors and API clients together before closing the bug. Keep one regression sample for every source.
Code Examples
{
"company": "AT&T",
"label": "Use < and > as text when rendering safely"
}const value = 'AT&amp;T';
console.log(value.includes('&amp;'));
// true: at least one layer was likely escaped twiceconst text = decodeHtmlEntities(api.description);
element.textContent = text; // safer than innerHTML for plain textCommon Mistakes
- Escaping text for HTML before putting it into a JSON API.
- Decoding entities and rendering the result as raw HTML.
- Treating plain text and sanitized HTML fields as the same contract.
- Fixing only the frontend while escaped values remain in storage.
- Decoding double-encoded text without finding where the second pass happens.
FAQ
Should JSON APIs return & for ampersands?
Usually no for plain text fields. JSON strings can contain ampersands directly.
What does &amp; mean?
It often means an already escaped ampersand was escaped again.
Is decoding HTML entities safe?
Decoding for text display can be fine, but rendering decoded content as HTML requires sanitization.
Should rich HTML fields be separate from text fields?
Yes. Clear field naming helps clients choose the right rendering path.