1. API host and authentication

First change to make: replace the GIPHY host with `https://heypster-gif.com/giphy`. Routes are protected by the `giphy.apikey` middleware; if your compatibility layer mirrors GIPHY, keep the `api_key` parameter.

If you already use native Heypster clients, the `HEYPSTER-API-KEY` header is still accepted. For a no-refactor GIPHY migration, keep `api_key`.

// GIPHY
fetch('https://api.giphy.com/v1/gifs/search?api_key=YOUR_GIPHY_API_KEY&q=clap');

// Heypster
fetch('https://heypster-gif.com/giphy/v1/gifs/search?api_key=YOUR_HEYPSTER_API_KEY&q=clap');

2. Endpoint mapping

3. Parameters to verify

4. Response parsing

• Do not rewrite parsers unless necessary: first validate `data`, `pagination`, `meta`, and `images` on a staging environment.
• Do not assume `pagination` is always present: some single-object and utility endpoints only return `data` and `meta`.
• Image variants are rebuilt from `gif_mini`, and video variants from `h264`.
• Verify your critical formats one by one: `original`, `fixed_width`, `fixed_height`, `downsized`, `preview_gif`, plus `mp4` and `webp` if your client consumes them.
• Do not depend on `webm`: the current contract exposes `webp` and `mp4`.
• For emoji payloads, objects use a GIPHY-like sticker shape; `url` points directly to the image asset and `/v2/emoji/{emoji_id}/variations` may return `data: []`.
• If your app reads secondary fields such as `analytics`, `user`, `source_tld`, or `alt_text`, review them explicitly before production.

const payload = await response.json();

const items = Array.isArray(payload.data) ? payload.data : [payload.data].filter(Boolean);
const nextOffset = payload.pagination?.offset ?? null;
const requestStatus = payload.meta?.status;

5. Full JavaScript example

const API_HOST = 'https://heypster-gif.com/giphy';
const API_KEY = 'YOUR_HEYPSTER_API_KEY';

export async function searchReactionGifs(query, offset = 0) {
    const url = new URL(`${API_HOST}/v1/gifs/search`);
    url.searchParams.set('api_key', API_KEY);
    url.searchParams.set('q', query);
    url.searchParams.set('limit', '24');
    url.searchParams.set('offset', String(offset));
    url.searchParams.set('lang', 'en');

    const response = await fetch(url.toString());
    const payload = await response.json();

    return {
        items: payload.data,
        pagination: payload.pagination,
        meta: payload.meta,
    };
}

// Examples for other mapped endpoints
fetch(`${API_HOST}/v1/gifs/categories?api_key=${API_KEY}`);
fetch(`${API_HOST}/v1/tags/related/party?api_key=${API_KEY}`);
fetch(`${API_HOST}/v1/randomid?api_key=${API_KEY}`);
fetch(`${API_HOST}/v2/emoji/1/variations?api_key=${API_KEY}`);

6. Migration checklist

• Replace `https://api.giphy.com` with `https://heypster-gif.com/giphy`.
• Replace the GIPHY key with the Heypster key.
• Test at least `search`, `trending`, `random`, and `get by id`.
• Verify any additional endpoints you use: `categories`, `related tags`, `randomid`, and `emoji`.
• Compare `offset` pagination between GIPHY and Heypster on your real use cases.
• Verify the exact formats your application consumes, especially `mp4` and `webp`.
• Confirm that your clients do not depend on `webm`.
• Audit any optional parameters your client sends, especially `rating`, `weirdness`, `bundle`, and `fields`.
• Confirm optional field behavior before production rollout.