Déploiement
Déploiement • Chapitre 6 : Déploiement d'une API REST

Configuration des URL et des endpoints

Structurez une architecture d'URL pérenne pour votre API en production : choix stratégique entre sous-domaine (api.mondomaine.com) et sous-chemin (/api/v1), conventions de versionnage et proxies Nginx.

🏷️
Versionnage /v1

Permet de faire évoluer votre API sans casser les applications mobiles existantes.

🌐
Sous-Domaine Dédié

api.mon-site.com offre une indépendance totale d'hébergement vis-à-vis du frontend.

🔀
Sous-Chemin /api

mon-site.com/api évite les contraintes CORS grâce à une origine identique.

📐
Conventions REST

Utilisation rigoureuse de ressources plurielles et des verbes GET, POST, PUT, DELETE.

nginx-routing-comparison.conf
# --- OPTION A : Routage par sous-chemin (mon-site.com/api/v1/) ---
server {
    server_name mon-site.com;

    # Frontend statique
    location / {
        root /var/www/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # Proxy vers l'API backend (Zéro problème CORS !)
    location /api/ {
        proxy_pass http://127.0.0.1:3000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# --- OPTION B : Routage par sous-domaine dédié (api.mon-site.com) ---
server {
    server_name api.mon-site.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Guide Approfondi & Architecture Système

1. Sous-Domaine vs Sous-Chemin : Quel Choix pour Votre Projet ?

Chaque approche possède des avantages décisifs :
  • Le Sous-Chemin (mon-site.com/api) : Idéal pour les petits et moyens projets. Puisque le frontend et l'API partagent exactement le même nom de domaine, la politique Same-Origin du navigateur s'applique : vous n'aurez aucun blocage CORS à configurer !
  • Le Sous-Domaine (api.mon-site.com) : Idéal pour les projets d'envergure. Il permet d'héberger l'API sur une machine puissante dans un centre de données dédié, tandis que le frontend reste sur un CDN mondial. En revanche, vous devrez autoriser le domaine frontend via les en-têtes CORS.

2. La Règle Capitale du Versionnage (/v1)

Ne publiez jamais d'API de production sans préfixe de version.
Pourquoi c'est vital : Si 500 utilisateurs ont installé votre application mobile sur leur smartphone et que vous modifiez la structure de votre JSON utilisateur le mois prochain, tous les téléphones qui n'ont pas fait la mise à jour vont crasher ! Avec /v1 et /v2, vous pouvez maintenir l'ancienne version active le temps que tout le monde migre.

Tableau Comparatif : Architectures d'URL pour API REST

CritèreOption A : Sous-Chemin (/api/v1)Option B : Sous-Domaine (api.site.com)
Gestion CORSAucune configuration requise (Même origine)Configuration CORS obligatoire dans l'API
Certificat SSLUn seul certificat couvre tout le siteNécessite un certificat Wildcard (*.site.com) ou distinct
Séparation d'infrastructureNécessite Nginx pour aiguiller les requêtesPeut pointer vers deux hébergeurs totalement séparés
Partage de cookiesNatif et directNécessite la configuration du domaine parent (.site.com)