Réécriture et scripts

Les règles de réécriture mockent, redirigent, retardent ou modifient les API sur l’appareil. Si une règle ne couvre pas un calcul dynamique, interceptez avec un script JavaScript.

Rédaction des scripts : Guide des scripts.

Sommaire

1. Portée (Scope)
2. Règles de réécriture
3. Scripts JavaScript

1. Portée (Scope)

La portée indique où s’applique une règle ou un script : Host + Path. Host est obligatoire ; Path est facultatif.

• Host : s’applique à toutes les requêtes de cet hôte. Correspondance floue : le domaine principal (example.com) suffit, les sous-domaines matchent aussi. Choisissez un hôte déjà capturé dans la liste, ou saisissez-le.
• Path (facultatif) : renseigné, seule cette API est visée. Path est préfixe uniquement (pas de joker *). /api/v1 matche /api/v1/users et /api/v1/orders. Après le Host, choisissez une API dans la liste (Method et Path se remplissent) ou saisissez le chemin.

Astuce : Choisir une API existante remplit Method et Path. Pour une règle de réécriture, ça préremplit aussi les modèles Mock ou les Headers.

2. Règles de réécriture

Quand le front et le back avancent en parallèle, l’API n’existe souvent pas encore, ou vous voulez des codes d’erreur. La réécriture couvre le Mock et les cas limites. Où ça s’applique : 1. Portée.

2.1 Rewrite Action

• Redirect : envoyer la requête ailleurs (prod → localhost ou staging).
• Mock : pas de réseau ; votre JSON/XML, statut (404, 500, …), en-têtes et corps.
• Drop :
  • Drop Request : comme si rien ne partait (hors ligne).
  • Drop Response : la requête part, aucune réponse (timeout).
• Delay : latence pour tester le Loading en réseau faible.
• Modify :
  • Header : injecter un jeton de test, changer le User-Agent.
  • Remplacer le Body : tout le corps requête ou réponse.
  • Regex dans le Body : patcher des champs JSON. Ex. "status": "pending" → "status": "success".

Si ça coince

• La règle ne prend pas : une règle plus récente, priorité plus haute, gagne.
• Le regex rate : le JSON a souvent des espaces et de l’indentation. Sans whitespace dans le motif (\s*), ça échoue. Utilisez le panneau Test.

3. Scripts JavaScript

Pour un Mock qui calcule (signature horodatée, données assemblées), le script est le bon outil. Même portée : 1. Portée.

3.1 Outils

Outre l’écriture à la main :

• Générer avec l’IA : décrivez en langage naturel (« mets price à 9.9 et ajoute discount_tag: true ») ; le JS standard est inséré.
• Test Script : testez sur une requête capturée avant d’enregistrer. Diff avant/après et erreurs. Vous pouvez aussi console.log et lire la sortie sur Logs.
• Remote Script : collez une URL publique http:// ou https://. ApiCatcher charge en local — pratique pour partager un Mock dans l’équipe.

3.2 Fonctions de cycle de vie

Détail : Guide des scripts

Implémentez les hooks :

// Requête sortante
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // Actions : passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

// Réponse entrante
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // parse JSON sûr
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

3.3 APIs intégrées

• localStore : état entre requêtes. Garder l’auth au login, l’injecter ensuite.
  • localStore.write('session_id', 'abc')
  • var t = localStore.read('session_id')
• httpClient : appels HTTP supplémentaires pendant le script (sync d’état externe, config).
  • var res = httpClient.get('https://api.ipify.org')

Si ça coince

• Syntaxe / runtime : Test Script. console.log("...") s’affiche sur Logs.
• Cycle de vie : si une réécriture plus prioritaire a déjà fait Mock ou Drop, le script ne tourne pas pour cette requête.