nostr-rest-api-field-mapping-gap

Nostr REST API Field Mapping Gap

Problem

Nostr clients that use both REST APIs and WebSocket connections to load events can have features that work inconsistently. Features that depend on Nostr tag values (like the x tag for sha256, or custom tags for text tracks) work when events are loaded via WebSocket (which provides the full raw event with all tags), but break when the same events are loaded via REST API (which returns flattened/denormalized JSON without the raw tags array).

Context / Trigger Conditions

• A feature works for some videos/events but not others (data source dependent)
• A UI element (like a CC button) shows for WebSocket-loaded events but not REST ones
• A model has null fields that should be populated (sha256, textTrackRef, etc.)
• The REST API response has fields like d_tag, video_url, title but NO tags array
• The fromJson() factory parses tags for values like x (sha256), but the REST API doesn't include raw tags
• hasSubtitles, hasFeature, or similar getters return false for REST API data

Root Cause

REST APIs that index Nostr events typically:

1. Extract commonly-used tag values into dedicated columns (d_tag, title, thumbnail, etc.)
2. Do NOT return the full raw tags array in their response
3. May have semantically equivalent fields under different names

For example, in a Blossom-based video system:

• The Nostr x tag contains the SHA256 content hash
• The REST API returns d_tag (which for Blossom uploads IS the SHA256) but not sha256
• The model's fromJson() tries to find sha256 from direct field or x tag, finds neither
• Features that depend on sha256 (like subtitle fetching) break silently

Solution

Step 1: Identify the mapping gap

Compare what the REST API returns vs what the model needs:

# Fetch a sample REST API response
curl -s "https://your-api.example.com/api/videos?limit=1" | jq '.[0] | keys'

Check which model fields are null after parsing:

• Look at the fromJson() factory method
• Identify fields populated from tag parsing (tags array) that won't exist in REST response
• Check if any REST API fields are semantically equivalent but differently named