Documentation

GIPHY → Heypster Migration

API GIPHY Migration

Drop-in migration

Reduce migration to a host and key change

If your product already uses the GIPHY REST API, Heypster is designed to preserve the same request mechanics: same `/v1` paths, same core parameters, and the same response shape. On `heypster-gif.com`, the compatible layer is prefixed with `/giphy`.

The right strategy is a two-step rollout: first swap the host and key, then validate secondary fields and the exact renditions your interface consumes.

1

Host to replace

1

API key to replace

0

heavy rewrite

Before / after

// before
const API_HOST = 'https://api.giphy.com';
const API_KEY = 'YOUR_GIPHY_API_KEY';

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

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. 

// 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

GIPHY Heypster
https://api.giphy.com/v1/gifs/search https://heypster-gif.com/giphy/v1/gifs/search
https://api.giphy.com/v1/gifs/trending https://heypster-gif.com/giphy/v1/gifs/trending
https://api.giphy.com/v1/gifs/translate https://heypster-gif.com/giphy/v1/gifs/translate
https://api.giphy.com/v1/gifs/random https://heypster-gif.com/giphy/v1/gifs/random
https://api.giphy.com/v1/gifs/search/tags https://heypster-gif.com/giphy/v1/gifs/search/tags
https://api.giphy.com/v1/gifs/categories https://heypster-gif.com/giphy/v1/gifs/categories
https://api.giphy.com/v1/tags/related/{term} https://heypster-gif.com/giphy/v1/tags/related/{term}
https://api.giphy.com/v1/trending/searches https://heypster-gif.com/giphy/v1/trending/searches
https://api.giphy.com/v1/randomid https://heypster-gif.com/giphy/v1/randomid
https://api.giphy.com/v1/emoji https://heypster-gif.com/giphy/v1/emoji
https://api.giphy.com/v2/emoji/{emoji_id}/variations https://heypster-gif.com/giphy/v2/emoji/{emoji_id}/variations
https://api.giphy.com/v1/gifs/{id} https://heypster-gif.com/giphy/v1/gifs/{id}
https://api.giphy.com/v1/gifs?ids=... https://heypster-gif.com/giphy/v1/gifs?ids=...

3. Parameters to verify

api_key

Keep the same parameter name. Only the value changes.

q, limit, offset, rating, lang

In a simple migration, these parameters usually remain unchanged.

ids

Multi-ID resolution can stay identical if your code already uses a comma-separated list.

term

The `/giphy/v1/tags/related/{term}` endpoint adds an explicit path parameter for related tags.

emoji_id

Emoji variations are served through `/giphy/v2/emoji/{emoji_id}/variations`.

random_id

If you use GIPHY analytics or personalization, verify on your Heypster environment whether this field is exposed and expected.

bundle / fields

If your code depends on advanced payload optimizations, validate their availability before final rollout.

4. Response parsing

  • Do not rewrite parsers unless necessary: first validate `data`, `pagination`, `meta`, and `images` on a staging environment.
  • If your app reads secondary fields such as `analytics`, `user`, `source_tld`, or `alt_text`, review them explicitly before production.
  • Verify your critical renditions one by one: `original`, `fixed_width`, `fixed_height`, `downsized`, and `preview_gif`.
const payload = await response.json();

const gifs = payload.data;
const nextOffset = payload.pagination?.offset ?? 0;
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 renditions your application consumes.
  • Confirm optional field behavior before production rollout.

Migration support

We can help audit an existing GIPHY integration, validate the diff before production rollout, and identify the fields your product should watch.

contact@heypster.com