Introduction aux API : comprendre le « dialogue entre programmes » depuis zéro

🎯 Question centrale

Qu'est-ce qu'une API ? C'est comme demander : comment concevoir le menu d'un restaurant pour que les clients comprennent du premier coup ? Comment le serveur note les commandes sans se tromper ? Les API résolvent précisément le problème du « dialogue entre programmes ». Vous utilisez des API depuis votre premier jour de code, même sans vous en rendre compte.

0. Trois confusions fréquentes chez les débutants

Confusion n°1 : Les API sont-elles un concept très avancé ?

Beaucoup de gens entendent parler d'API et pensent qu'il s'agit d'un concept réservé aux ingénieurs seniors. En réalité, vous avez déjà utilisé des API depuis longtemps :

python

len("hello")        # C'est une API fournie par Python
open("file.txt")    # C'est aussi une API
requests.get(url)   # C'est encore une API

Confusion n°2 : Quelle est la différence entre une API Web et une API classique ?

Type	Cible appelée	Mode de communication	Scénario typique
API de fonction	Code local	Appel de fonction	`len()`, `open()`
API du système d'exploitation	Système d'exploitation	Appel système	Lecture/écriture de fichiers, création de processus
API Web	Serveur distant	Requête HTTP	Appel à un modèle IA, récupération de la météo

Confusion n°3 : Dois-je utiliser HTTP ou un SDK ?

python

# Approche HTTP : vous gérez tous les détails vous-même
import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

# Approche SDK : le gestionnaire s'occupe de tout
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

1. L'essence des API : la prise et la prise murale

Une API (Application Programming Interface, interface de programmation d'application) est un « contrat de dialogue entre programmes ».

1.1 Analogie avec les appareils électriques

Concept	Analogie électrique	Correspondance API
Interface	Forme de la prise	Signature de fonction / URL
Entrée	Courant entrant	Paramètres de fonction / Corps de la requête
Sortie	L'appareil fonctionne	Valeur de retour / Corps de la réponse

1.2 Comparaison des trois types d'API

TargetLocal code library

CommunicationFunction call

LatencyNanoseconds

Typical scenariosData processing, file operations

Function API example

len("hello")           # returns 5
max([1, 5, 3])         # returns 5
open("file.txt").read() # reads a file

1.3 Différence entre API de fonction et API HTTP

Beaucoup de débutants se posent la question : quelle est la différence entre une API de fonction et une API HTTP ? Comment les distinguer dans la documentation ?

📚 Function API vs HTTP APILocal calls vs network requests: how should you read the docs?

📦Function API

Call styleDirect function call

ParametersArguments inside parentheses

Return valueReturn value directly

Error handlingException or return value

Python example

# Call a built-in function
length = len("hello")      # returns 5

# Call a library function
import math
result = math.sqrt(16)     # returns 4.0

# Call a custom function
def add(a, b):
    return a + b
sum = add(3, 5)            # returns 8

🌐HTTP API

Call styleNetwork request

ParametersURL / body / headers

Return valueJSON/XML response

Error handlingStatus code checks

HTTP request example

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Core point:A function API works locally; an HTTP API communicates remotely. Function docs focus on parameters and return values, while HTTP API docs focus on endpoint, authentication, and request/response formats.

1.4 Comment lire les différents types de documentation API

Face à différents types de documentation API, les points d'attention varient :

📋 How to Read Different Doc TypesFunction docs, REST API docs, and SDK docs each emphasize different things

Doc typeFunction docs

Best forUsing standard library or third-party functions

Difficulty⭐⭐

🔍 What to focus on

Function signatureParameter typesReturn valueExceptionsExample code

📝Doc example

### json.loads(s, *, cls=None, object_hook=None...)

Parse a JSON string into a Python object.

**Parameters:**
- s (str): JSON string to parse
- cls (JSONDecoder): Custom decoder class
- object_hook (callable): Optional conversion function

**Returns:**
- dict | list: Parsed Python object

**Raises:**
- JSONDecodeError: The string is invalid JSON

**Example:**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

💡Reading tips

Read the function signature first to see what parameters are needed.
Check parameter types and whether each parameter is required.
Check the return type so later code can handle it correctly.
Notice possible exceptions and prepare error handling.

📊Quick comparison of three doc types

Item

Function docs

REST API docs

SDK docs

Core focus

Parameters, return values

Endpoint, request body

Initialization, method chain

Code example

Function call

HTTP request

Object method

Error handling

Exceptions/return values

Status codes

Exception objects

Read first

Function signature

Base URL + Auth

Quick Start

Reading advice:For function docs, read the signature. For API docs, read the request format. For SDK docs, read examples first. When stuck, look for Quick Start or Getting Started.

2. Un appel API complet

👇 Essayez par vous-même : cliquez sur le bouton ci-dessous et observez un flux complet de requête-réponse API :

API Request Demo

// Click a command below to simulate API requests

> ▋

💻ClientSends request

Waiting for request...

HTTP Request→

🖥️ServerHandles request

Waiting...

HTTP Response←

📦ResponseReturns result

Waiting for response...

💡 Click a command button to observe a complete API request-response flow.

2.1 Les quatre phases d'un appel API

Phase	Ce qui se passe	Analogie électrique
Requête	Le client envoie une requête au serveur	Appuyer sur l'interrupteur
Transmission	La requête transite via le réseau jusqu'au serveur	Le courant passe dans les fils
Traitement	Le serveur traite la requête et renvoie des données	L'appareil se met en marche
Réponse	Le client reçoit et traite le résultat renvoyé	L'ampoule s'allume

2.2 Analogie avec le restaurant

Rôle au restaurant	Correspondance API	Explication
Menu	Documentation API	Vous indique quels « plats » sont disponibles
Serveur	Protocole HTTP	Un « mode de dialogue » standardisé
Cuisine	Côté serveur	Traite les requêtes selon les « commandes »
Service à table	Réponse	Renvoie le résultat au « client »

3. Méthodes HTTP : êtes-vous en train de « demander » ou de « faire » ?

Lorsque vous appelez une API Web, vous devez indiquer au serveur ce que vous voulez faire. C'est l'origine des méthodes HTTP.

3.1 Comprendre avec la commande au restaurant

Scénario	Comment diriez-vous dans la réalité ?	Méthode HTTP correspondante
Vous voulez savoir quels plats sont disponibles aujourd'hui	« Serveur, montrez-moi le menu »	GET -纯粹的 « demander », sans modifier les données
Vous voulez commander un poulet Kung Pao	« Je prends un poulet Kung Pao »	POST - « Faire » quelque chose, créer des données
Vous voulez changer un plat	« Remplacez le poulet Kung Pao par du porc à la sauce aigre-douce »	PUT - Remplacer les données
Vous voulez modifier l'assaisonnement	« Pas de cacahuètes dans le poulet Kung Pao »	PATCH - Modification partielle
Vous ne voulez plus ce plat	« Laissez tomber, annulez ce plat »	DELETE - Supprimer les données

get

Read

Query data

Idempotent

post

Create

Add data

Not idempotent

put

Full update

Replace resource

Idempotent

patch

Partial update

Modify fields

Not idempotent

delete

Delete

Remove resource

Idempotent

getRead - Query data

Fetch resources from the server without changing data

Restaurant analogy:"Waiter, show me the menu"

GET /api/users           # fetch user list
GET /api/users/123       # fetch one user
GET /api/products?cat=phone  # query phone products

À propos de l'idempotence

Idempotence : l'exécution multiple produit-elle le même résultat ?

Opérations idempotentes (GET/PUT/DELETE) : cliquer 10 fois ou 1 fois, le résultat est identique
Opérations non idempotentes (POST) : cliquer 10 fois peut créer 10 commandes

Solution : utiliser un identifiant unique pour les opérations POST afin d'éviter le traitement en double.

3.2 Aide-mémoire des méthodes HTTP

Méthode	Usage	Idempotence	Sécurité	Scénario typique
GET	Récupérer une ressource	Oui	Oui	Liste de résultats, afficher les détails
POST	Créer une ressource	Non	Non	Ajouter un utilisateur, soumettre une commande
PUT	Mise à jour complète	Oui	Non	Remplacer le profil utilisateur complet
PATCH	Mise à jour partielle	Non	Non	Modifier uniquement le pseudo
DELETE	Supprimer une ressource	Oui	Non	Supprimer un utilisateur, annuler une commande

4. Codes d'état HTTP : que vous dit le serveur ?

Lorsque le serveur répond, il renvoie d'abord un code d'état pour vous indiquer si la requête a réussi.

4.1 Catégories de codes d'état

2xxSuccess

The request was received, understood, and processed successfully

200 OK201 Created204 No Content

3xxRedirect

More action is needed to complete the request

301 Moved Permanently304 Not Modified307 Temporary Redirect

4xxClient error

The request has an error or cannot be completed

400 Bad Request401 Unauthorized403 Forbidden404 Not Found

5xxServer error

The server failed to handle a valid request

500 Internal Error502 Bad Gateway503 Unavailable

💡Memory tip:2️⃣ Success • 3️⃣ Redirect • 4️⃣ Client error • 5️⃣ Server error

4.2 Détails des codes d'état courants

Code d'état	Signification	Scénario typique	Traitement côté client
200 OK	Succès	Requête traitée normalement	Afficher les données
201 Created	Création réussie	Requête POST a créé une ressource avec succès	Rediriger vers la nouvelle ressource
400 Bad Request	Format de requête incorrect	Paramètre manquant ou format incorrect	Vérifier les paramètres
401 Unauthorized	Non authentifié	Aucune clé API valide fournie	Guider l'utilisateur vers la connexion
403 Forbidden	Non autorisé	La clé API n'a pas les droits d'accès à cette ressource	Indiquer des droits insuffisants
404 Not Found	N'existe pas	L'adresse ou la ressource demandée n'existe pas	Vérifier l'URL
429 Too Many Requests	Trop de requêtes	Limite de débit dépassée	Réessayer plus tard
500 Internal Server Error	Erreur serveur	Problème côté serveur	Inviter l'utilisateur à réessayer plus tard

👇 Essayez par vous-même : cliquez sur le bouton ci-dessous pour comprendre la signification des codes d'état courants :

HTTP Status Code Demo

// Click a button to inspect status code meanings

> ▋

✅2xx Success

200OKRequest succeeded

201CreatedResource created

204No ContentSucceeded with no response body

⚠️4xx Client errors

400Bad RequestMalformed request

401UnauthorizedNot authenticated

403ForbiddenNo permission

404Not FoundResource missing

422UnprocessableSemantic validation error

429Too ManyToo many requests

🔴5xx Server errors

500Server ErrorInternal server error

502Bad GatewayGateway error

503UnavailableService unavailable

💡 Click a command button to learn common HTTP status codes.

5. HTTP vs SDK : faire les courses vous-même ou déléguer à un gestionnaire ?

5.1 Comparaison des deux modes d'appel

	🏃 API HTTP	🤵 SDK
Analogie	Faire les courses soi-même	Déléguer à un gestionnaire
Avantages	✓ Utilisable dans tous les langages ✓ Contrôle total des détails de la requête ✓ Pas de dépendance supplémentaire	✓ Code concis et lisible ✓ Gestion automatique de l'authentification ✓ Nouvelles tentatives d'erreur intégrées
Inconvénients	✗ Nécessite de gérer tous les détails ✗ Code verbeux et sujet aux erreurs	✗ Nécessite d'installer des dépendances ✗ Possibles problèmes de version
Exemple de code	`requests.post(url, json=..., headers={...})`	`client.chat.completions.create(...)`

5.2 Comment choisir ?

Scénario	Approche recommandée	Raison
Développement rapide	SDK	Gestion automatique de l'authentification, des erreurs, des nouvelles tentatives
Apprentissage des principes	HTTP	Comprendre les mécanismes sous-jacents
Langage non supporté	HTTP	Utilisable dans n'importe quel langage
Besoin de personnalisation	HTTP	Contrôle flexible de chaque détail

💡 Conseil

Utilisez le SDK quand c'est possible, laissez les tâches ingrates à la bibliothèque, gardez votre temps pour vous.

6. Comment lire une documentation API ?

La documentation API est comme un hybride entre un manuel d'utilisation et un menu. Vous n'avez pas besoin de la lire de bout en bout, il suffit d'apprendre à « consulter le dictionnaire ».

6.1 Liste de contrôle pour la lecture de documentation

Ouvrez n'importe quelle documentation API (par exemple OpenAI ou DeepSeek), vous n'avez besoin de chercher que ces éléments :

📖API Document Translator

Base URL

https://api.deepseek.com

Endpoint

POST /v1/chat/completions

Headers

Authorization: Bearer sk-xxx
Content-Type: application/json

Body parameters

modelRequiredModel name

messagesRequiredConversation messages

temperatureOptional0-2, default 1

Translate into code

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)

Core idea:When reading docs, find three things: address (Base URL), authentication (Authorization), and parameters.

Élément	Description	Exemple
URL de base	L'adresse racine de l'API	`https://api.deepseek.com`
Authentification	Comment prouver votre identité	`Authorization: Bearer sk-xxx`
Endpoints	La liste spécifique des interfaces	`/v1/chat/completions`
Paramètres	Paramètres obligatoires/optionnels	`model` (obligatoire), `temperature` (optionnel)
Réponse	Structure des données renvoyées	`{"choices": [...]}`

6.2 Étapes pour lire la documentation

Trouver l'URL de base - c'est le préfixe de toutes les requêtes
Comprendre le mode d'authentification - La clé API va-t-elle dans le Header ou dans les Query ?
Trouver l'Endpoint nécessaire - L'interface spécifique que vous voulez appeler
Consulter les paramètres de la requête - Lesquels sont obligatoires ? Lesquels sont optionnels ?
Comprendre le format de réponse - Comment les données sont-elles organisées ?

7. Exercice pratique : simuler un appel API

La pratique vaut mieux que la théorie. Voici une API simulée où vous pouvez remplir n'importe quels paramètres et modifier l'adresse comme vous le souhaitez, pour voir ce qui se passe.

🧪API PlaygroundTry calls without touching a real server

Endpoint

Method

API Key

Send a request to see the response

Quick tries:

Essayez de déclencher les scénarios suivants :

✅ Requête réussie : remplissez le bon Endpoint et la clé API
❌ Erreur 401 : ne remplissez pas la clé API, voyez comment le serveur vous refuse
❌ Erreur 404 : remplissez une adresse qui n'existe pas

8. Résumé

Points clés

Les API sont un porte-voix, elles transmettent votre message à un autre bout de code ou à un serveur distant
Vous utilisez déjà des API, de len() à open(), tout est API
Les API Web sont un super-pouvoir, vous permettant d'appeler des super-ordinateurs à des milliers de kilomètres
Le SDK est un bon gestionnaire, utilisez le SDK quand c'est possible plutôt que de faire les courses vous-même
Cherchez trois choses dans la documentation : adresse, authentification, paramètres

À l'ère de la programmation IA, vous n'avez besoin de retenir que ces quelques concepts essentiels. Le reste des détails, l'IDE et l'assistant IA s'en chargeront pour vous.

Glossaire

Terme	Nom complet	Explication
API	Application Programming Interface	Interface de programmation d'application, définit comment les logiciels interagissent
Web API	-	API basée sur le protocole HTTP, utilisée pour la communication réseau
Endpoint	-	Point de terminaison, l'adresse spécifique d'une API
HTTP	HyperText Transfer Protocol	Protocole de communication utilisé par les API Web
GET	-	Méthode pour récupérer une ressource
POST	-	Méthode pour soumettre des données
SDK	Software Development Kit	Kit de développement logiciel, encapsule les appels API bas niveau
URL	Uniform Resource Locator	L'adresse réseau d'une API
JSON	JavaScript Object Notation	Format de données couramment utilisé
Authentication	-	Processus de vérification d'identité
Status Code	-	Code d'état dans la réponse HTTP
Request	-	Requête
Response	-	Réponse
Header	-	En-tête HTTP, contient des métadonnées
Payload	-	Les données réelles de la requête ou de la réponse
Rate Limit	-	Limite de débit
Idempotent	-	Idempotent, l'exécution multiple produit le même résultat
REST	Representational State Transfer	Un style d'architecture API
RPC	Remote Procedure Call	Appel de procédure à distance
GraphQL	-	Un langage de requête API
gRPC	-	Framework RPC haute performance développé par Google

Introduction aux API : comprendre le « dialogue entre programmes » depuis zéro ​

0. Trois confusions fréquentes chez les débutants ​

1. L'essence des API : la prise et la prise murale ​

1.1 Analogie avec les appareils électriques ​

1.2 Comparaison des trois types d'API ​

1.3 Différence entre API de fonction et API HTTP ​

1.4 Comment lire les différents types de documentation API ​

2. Un appel API complet ​

2.1 Les quatre phases d'un appel API ​

2.2 Analogie avec le restaurant ​

3. Méthodes HTTP : êtes-vous en train de « demander » ou de « faire » ? ​

3.1 Comprendre avec la commande au restaurant ​

3.2 Aide-mémoire des méthodes HTTP ​

4. Codes d'état HTTP : que vous dit le serveur ? ​

4.1 Catégories de codes d'état ​

4.2 Détails des codes d'état courants ​

5. HTTP vs SDK : faire les courses vous-même ou déléguer à un gestionnaire ? ​

5.1 Comparaison des deux modes d'appel ​

5.2 Comment choisir ? ​

6. Comment lire une documentation API ? ​

6.1 Liste de contrôle pour la lecture de documentation ​

6.2 Étapes pour lire la documentation ​

7. Exercice pratique : simuler un appel API ​

8. Résumé ​

Glossaire ​

Introduction aux API : comprendre le « dialogue entre programmes » depuis zéro

0. Trois confusions fréquentes chez les débutants

1. L'essence des API : la prise et la prise murale

1.1 Analogie avec les appareils électriques

1.2 Comparaison des trois types d'API

1.3 Différence entre API de fonction et API HTTP

1.4 Comment lire les différents types de documentation API

2. Un appel API complet

2.1 Les quatre phases d'un appel API

2.2 Analogie avec le restaurant

3. Méthodes HTTP : êtes-vous en train de « demander » ou de « faire » ?

3.1 Comprendre avec la commande au restaurant

3.2 Aide-mémoire des méthodes HTTP

4. Codes d'état HTTP : que vous dit le serveur ?

4.1 Catégories de codes d'état

4.2 Détails des codes d'état courants

5. HTTP vs SDK : faire les courses vous-même ou déléguer à un gestionnaire ?

5.1 Comparaison des deux modes d'appel

5.2 Comment choisir ?

6. Comment lire une documentation API ?

6.1 Liste de contrôle pour la lecture de documentation

6.2 Étapes pour lire la documentation

7. Exercice pratique : simuler un appel API

8. Résumé

Glossaire