1. Hôte API et authentification

Premier changement à effectuer : remplacez l’hôte GIPHY par `https://heypster-gif.com/giphy`. Les routes sont protégées par le middleware `giphy.apikey` ; si votre couche de compatibilité reproduit GIPHY, gardez le paramètre `api_key`.

Si vous utilisez déjà des clients Heypster natifs, l’en-tête `HEYPSTER-API-KEY` reste accepté. Pour une migration GIPHY sans refactor, conservez néanmoins `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. Correspondance des endpoints

3. Paramètres à vérifier

4. Parsing des réponses

• Ne réécrivez pas vos parseurs sans nécessité : commencez par valider `data`, `pagination`, `meta` et `images` sur un environnement de staging.
• Ne supposez pas que `pagination` est toujours présente : certaines réponses unitaires et certains endpoints utilitaires renvoient seulement `data` et `meta`.
• Les déclinaisons image sont reconstruites à partir de `gif_mini`, et les déclinaisons vidéo à partir de `h264`.
• Vérifiez vos déclinaisons critiques une par une : `original`, `fixed_width`, `fixed_height`, `downsized`, `preview_gif`, ainsi que `mp4` et `webp` si votre client les consomme.
• Ne dépendez pas de `webm` : le contrat actuel expose `webp` et `mp4`.
• Pour les emojis, le payload reprend une forme proche des stickers GIPHY ; `url` pointe directement vers l’image et `/v2/emoji/{emoji_id}/variations` peut renvoyer `data: []`.
• Si votre application lit des champs secondaires comme `analytics`, `user`, `source_tld` ou `alt_text`, faites une revue explicite avant mise en 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. Exemple complet en JavaScript

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', 'fr');

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

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

// Exemples d'autres endpoints mappés
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. Checklist de migration

• Remplacez `https://api.giphy.com` par `https://heypster-gif.com/giphy`.
• Remplacez la clé GIPHY par la clé Heypster.
• Testez au minimum `search`, `trending`, `random` et `get by id`.
• Vérifiez les endpoints additionnels réellement utilisés : `categories`, `related tags`, `randomid` et `emoji`.
• Comparez la pagination `offset` entre GIPHY et Heypster sur vos cas d’usage réels.
• Vérifiez les formats réellement utilisés dans votre application, en particulier `mp4` et `webp`.
• Confirmez que vos clients ne dépendent pas de `webm`.
• Auditez les paramètres optionnels envoyés par votre client, notamment `rating`, `weirdness`, `bundle` et `fields`.
• Validez le comportement des champs optionnels avant la mise en production.