Fondamentaux des API

Avant de construire une API, il faut comprendre ce que ce terme signifie réellement et quelles formes il peut prendre.

Qu'est-ce qu'une API ?

API signifie Application Programming Interface (Interface de Programmation d'Application). C'est un système de communication entre deux systèmes qui abstrait la complexité de l'application sous-jacente.

Une API permet à deux logiciels d'échanger des données sans que l'un ait besoin de connaître les détails d'implémentation de l'autre.

Analogie simple

Pensez à un restaurant :

• Le client (vous) passe une commande au serveur
• Le serveur (l'API) transmet la commande en cuisine
• La cuisine (le backend) prépare le plat
• Le serveur vous ramène le résultat

Vous n'avez pas besoin de savoir comment la cuisine fonctionne. L'API (le serveur) est l'interface entre vous et la complexité.

Les différents types d'API web

Dans le contexte du web, plusieurs architectures et protocoles coexistent :

REST (Representational State Transfer)

C'est l'architecture la plus répandue sur le web. Elle repose sur HTTP et utilise les méthodes HTTP (GET, POST, PUT, DELETE) pour manipuler des ressources. Le format d'échange le plus courant est JSON.

# Exemple de réponse REST en JSON
{
    "id": 1,
    "title": "Clean Architecture",
    "author": "Robert C. Martin",
    "year": 2017
}

SOAP (Simple Object Access Protocol)

Protocole basé sur XML avec un contrat strict (WSDL). Toujours utilisé dans certains secteurs comme la banque ou l'assurance où la rigueur des échanges est primordiale.

<!-- Exemple de requête SOAP -->
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetBook>
      <BookId>1</BookId>
    </GetBook>
  </soap:Body>
</soap:Envelope>

GraphQL

Développé par Facebook, GraphQL permet au client de demander exactement les données dont il a besoin, ni plus, ni moins. Cela évite le problème d'over-fetching (trop de données) ou d'under-fetching (pas assez de données en un seul appel).

# Le client choisit précisément les champs souhaités
query {
  book(id: 1) {
    title
    author {
      name
    }
  }
}

gRPC

Format binaire développé par Google, basé sur Protocol Buffers. Très performant pour la communication entre micro-services grâce à sa sérialisation compacte.

WebSockets et Server-Sent Events (SSE)

Pour les cas nécessitant du temps réel :

• WebSockets : communication bidirectionnelle (chat, jeux en ligne)
• SSE : flux unidirectionnel du serveur vers le client (notifications, streaming de données)

JSON : le format d'échange dominant

JSON (JavaScript Object Notation) est le format d'échange le plus utilisé dans les API web modernes. Il est lisible par les humains et facilement parsable par les machines.

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "roles": ["admin", "user"]
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com",
      "roles": ["user"]
    }
  ],
  "total": 2
}

En Python, la manipulation du JSON se fait avec le module json intégré, mais avec Flask et Pydantic, la sérialisation est généralement automatique.

À retenir