NOVATECHDEVELOPER PLAYGROUNDOuvrir NOVATECH →
TUTORIEL PRATIQUE · INTÉGRATION API

Construire avec l’API UDCShare.

Ce cours accompagne un développeur qui télécharge le code des exemples et veut intégrer UDCShare dans sa propre application : site web, application mobile, outil métier, service SaaS ou script d’automatisation. Tu choisis ton langage, ton hébergeur et ta base de données.

NOVATECH présente ce tutoriel et permet d'expérimenter. Render et Supabase ne sont pas des prérequis pour utiliser l’API UDCShare. Tu peux héberger ton application où tu veux, ou l’exécuter localement.

1. Comprendre ce que fournit l'API

Une API REST permet à ton application de demander à UDCShare d'effectuer des opérations sans reproduire toute la plateforme. Ton application envoie une requête HTTP ; l'API répond généralement avec des données JSON.

Ton application

Interface, comptes de tes utilisateurs, règles métier et expérience utilisateur.

API UDCShare

Opérations de fichiers et services UDCShare accessibles selon ta clé et ta formule.

Le point d'entrée API v1 est https://udcshare.com/api/v1. NOVATECH est conçu pour les clés Developer Console liées à une ressource API de projet.

La documentation interactive et le schéma OpenAPI décrivent les routes, paramètres, champs requis et réponses à jour. Consulte-les avant d'intégrer une opération.

Ouvrir Swagger — documentation interactive · Consulter OpenAPI JSON

2. Obtenir tes identifiants API

  1. Connecte-toi à ton compte UDCShare.
  2. Ouvre le tableau de bord, rubrique Développeur.
  3. Crée ou consulte une clé API selon les options proposées par ton compte.
  4. Copie la clé et conserve-la dans un gestionnaire de secrets ou dans un fichier local .env non versionné.

Accéder à la rubrique Développeur UDCShare

Pour NOVATECH : enregistre la clé API et l'identifiant public api_client_id de la ressource API du projet. Cet identifiant n'est pas l'UUID interne du projet. Les routes de fichiers projet utilisent /apps/{clientId}/.... Les anciennes routes /account, /upload et /files restent réservées aux clés historiques non liées à un projet.

3. Effectuer ton premier appel API

Pour une clé Developer Console liée à un projet, commence par lire les quotas puis vérifie la ressource API :

curl https://udcshare.com/api/v1/usage \
  -H "X-API-Key: VOTRE_CLE_API"

curl "https://udcshare.com/api/v1/apps/VOTRE_API_CLIENT_ID/status" \
  -H "X-API-Key: VOTRE_CLE_API"

Exemple JavaScript côté serveur (Node.js 18+) :

const API_BASE = "https://udcshare.com/api/v1";
const API_CLIENT_ID = process.env.UDCSHARE_API_CLIENT_ID;

const response = await fetch(`${API_BASE}/apps/${encodeURIComponent(API_CLIENT_ID)}/status`, {
  headers: {
    "X-API-Key": process.env.UDCSHARE_API_KEY
  }
});

const data = await response.json();
if (!response.ok) throw new Error(`Erreur API : HTTP ${response.status}`);
console.log(data);

Dans ton fichier local .env, définis UDCSHARE_API_KEY=ta_cle, puis charge les variables avec l'outil adapté à ton environnement. Ne publie jamais ce fichier.

4. Comprendre les méthodes HTTP

Les méthodes indiquent le type d'action demandé. Les routes et leurs paramètres exacts sont définis dans Swagger.

GETLire

Consulter le compte, une liste de fichiers ou des statistiques.

POSTCréer ou envoyer

Envoyer un fichier ou déclencher une opération de création, selon la route.

PUT / PATCHModifier

Mettre à jour une ressource uniquement si la route correspondante est documentée.

DELETESupprimer

Supprimer une ressource en utilisant son identifiant et les droits associés.

Routes utilisées par NOVATECH pour une clé de projet :

GET /api/v1/apps/{clientId}/statusGET /api/v1/apps/{clientId}/filesPOST /api/v1/apps/{clientId}/filesDELETE /api/v1/apps/{clientId}/files/{fileId}GET /api/v1/statsGET /api/v1/usage
Ne devine jamais une route PUT, PATCH ou une route de création de transfert à partir de son nom. Si elle n'apparaît pas dans Swagger/OpenAPI, ne la considère pas comme une opération prise en charge.

5. Envoyer un fichier

Pour une ressource de projet, l'envoi utilise POST /apps/{clientId}/files avec un corps multipart/form-data et un champ nommé file. En mode API-only / Drive individuel, le backend doit également fournir un X-External-User-ID stable, opaque et calculé côté serveur.

curl -X POST "https://udcshare.com/api/v1/apps/VOTRE_API_CLIENT_ID/files" \
  -H "X-API-Key: VOTRE_CLE_API" \
  -H "X-External-User-ID: identifiant-utilisateur-stable" \
  -F "file=@./document.pdf"

Les anciennes clés historiques non liées à un projet utilisent encore POST /upload ; ne mélange pas les deux contrats.

Pour l'envoi, ne définis pas toi-même l'en-tête Content-Type avec une boundary fixe : laisse cURL ou ton client HTTP générer le bon multipart. Pour les fichiers volumineux, respecte les tailles maximales, quotas, délais et mécanismes de transfert indiqués par la documentation de l'API.

Le résultat peut contenir un identifiant ou un lien selon le contrat de réponse réel de la route. Lis le JSON reçu et utilise les noms de champs documentés ; ne suppose pas leur forme.

6. Intégrer l'API dans ta propre application

Architecture recommandée

  1. Ton interface (React, Vue, HTML, application mobile) envoie une demande à ton propre backend.
  2. Ton backend authentifie l'utilisateur de ton application et vérifie ses droits.
  3. Le backend appelle UDCShare avec la clé API conservée côté serveur.
  4. Ton backend renvoie à l'interface uniquement les données nécessaires.
  5. Tu peux enregistrer dans ta propre base les métadonnées utiles à ton produit.

Exemple de route backend Express

import express from "express";

const app = express();

app.get("/api/udcshare/account", async (req, res) => {
  try {
    const upstream = await fetch(
      "https://udcshare.com/api/v1/account",
      {
        headers: {
          "X-API-Key": process.env.UDCSHARE_API_KEY
        }
      }
    );

    const body = await upstream.json();
    res.status(upstream.status).json(body);
  } catch {
    res.status(502).json({ error: "UDCShare temporairement inaccessible" });
  }
});

app.listen(3000);

Le code est un squelette pédagogique : ajoute l'authentification de tes utilisateurs, la validation des entrées, la limitation de débit et une gestion d'erreurs adaptée avant la mise en production.

Langages disponibles dans le dépôt

Les exemples téléchargeables couvrent JavaScript, React, Vue, Node.js, Python, PHP et Go. Tu peux adapter la même architecture à Laravel, Symfony, Django, FastAPI, .NET ou à un autre environnement HTTP.

7. Lire les réponses et traiter les erreurs

Une réponse HTTP contient un code de statut et, souvent, un corps JSON. Vérifie toujours response.ok ou le code HTTP avant d'utiliser le résultat.

200 / 201

Requête réussie ou ressource créée. Lis le corps de réponse.

400 / 422

Entrée invalide ou paramètres manquants. Corrige la requête.

401 / 403

Clé non valide, accès ou formule insuffisante. Vérifie les droits.

413 / 429

Fichier trop volumineux ou limite de requêtes/quota atteinte.

5xx

Erreur serveur ou service temporairement indisponible. Réessaie prudemment.

Le format précis des erreurs dépend de la route. Affiche un message compréhensible à l'utilisateur, conserve le code HTTP pour le diagnostic et évite d'exposer les secrets ou les détails internes du serveur.

8. Sécuriser ton intégration

  • Clé API : conserve-la côté serveur dans une variable d'environnement ou un gestionnaire de secrets.
  • Navigateur : ne mets jamais une clé secrète dans React, Vue, JavaScript public, HTML ou une application mobile distribuée.
  • Git : ajoute .env à .gitignore ; ne commite jamais une clé.
  • Comptes : authentifie les utilisateurs de ton application et vérifie qu'ils ne peuvent accéder qu'à leurs propres ressources.
  • Quotas : contrôle les appels et évite les boucles de retry agressives.
  • Transport : utilise HTTPS et masque les clés dans les logs.
Le dépôt contient aussi un ancien exemple JavaScript navigateur qui instancie le client avec une clé API. Ne reproduis pas ce modèle avec une clé secrète en production : privilégie le backend relais présenté dans ce tutoriel, sauf si UDCShare documente explicitement un mécanisme public adapté.

9. Télécharger les exemples de code

Le dépôt public contient des projets de départ. Clone-le, ouvre le dossier du langage choisi et suis son README. Chaque exemple peut être adapté à ton infrastructure ; tu n'es pas obligé d'utiliser NOVATECH.

git clone https://github.com/SALEMEDO/udcshare-api-examples.git
cd udcshare-api-examples
# Choisir ensuite le dossier de l'exemple voulu

10. Ton parcours de réalisation

  1. Crée un projet et sa ressource API dans Developer Console, puis récupère la clé et le api_client_id.
  2. Lis GET /usage et vérifie GET /apps/{clientId}/status.
  3. Liste les fichiers avec GET /apps/{clientId}/files.
  4. Ajoute un fichier avec POST /apps/{clientId}/files.
  5. Teste la suppression avec DELETE /apps/{clientId}/files/{fileId} sur un fichier de test.
  6. Consulte GET /stats, puis teste les erreurs, quotas et droits.
  7. Garde la clé et l'identifiant externe côté backend, jamais dans le navigateur.
Besoin d'une réponse précise ? Ouvre Swagger, sélectionne une route, regarde ses paramètres et son exemple de réponse, puis reproduis-la dans ton langage. C'est la référence à suivre pour la version actuelle de l'API.

Explorer l'API dans Swagger → Essayer NOVATECH