RESTFUL
API

Une API REST (Representational State Transfer) est une interface qui permet à deux systèmes de communiquer via HTTP. Le client envoie une requête, le serveur renvoie une réponse — généralement en JSON.

REST n'est pas un protocole mais un style d'architecture basé sur 6 contraintes : stateless, client-serveur, cacheable, interface uniforme, système en couches, code on demand (optionnel).

La façon la plus directe de tester une API depuis le terminal.

# GET — récupérer une ressource
curl https://jsonplaceholder.typicode.com/users/1

# GET avec headers et pretty print
curl -s -H "Accept: application/json" \
     https://jsonplaceholder.typicode.com/posts | python3 -m json.tool

# POST — créer une ressource
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"title": "Boss Fight", "userId": 1}' \
     https://jsonplaceholder.typicode.com/posts

# DELETE — supprimer
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

# Avec API Key dans le header
curl -H "Authorization: Bearer TON_TOKEN" \
     https://api.exemple.com/protected

Flask rend le développement d'API REST simple et lisible avec un système de routing élégant.

from flask import Flask, jsonify, request, abort

app = Flask(__name__)

# Données en mémoire (remplacer par DB en prod)
users = [{"id": 1, "name": "Adam"}]

# GET /api/users — liste tous les users
@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify(users), 200

# GET /api/users/<id> — un seul user
@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    user = next((u for u in users if u["id"] == user_id), None)
    if not user:
        abort(404)
    return jsonify(user), 200

# POST /api/users — créer un user
@app.route('/api/users', methods=['POST'])
def create_user():
    data = request.get_json()
    if not data or 'name' not in data:
        abort(400)   # Bad Request
    new_user = {"id": len(users) + 1, "name": data["name"]}
    users.append(new_user)
    return jsonify(new_user), 201  # 201 Created

# DELETE /api/users/<id>
@app.route('/api/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
    global users
    users = [u for u in users if u["id"] != user_id]
    return '', 204  # 204 No Content

if __name__ == '__main__':
    app.run(debug=True, port=5000)

══════════════════════════════════════════════════════════════
                    RESTFUL API — CARTE MENTALE
══════════════════════════════════════════════════════════════

CLIENT ──────── HTTP REQUEST ────────► SERVER
  │                                      │
  │  Méthodes :                          │  Logique :
  │  GET    → lire une ressource         │  Valide le body
  │  POST   → créer                      │  Authentifie
  │  PUT    → remplacer                  │  Interroge la DB
  │  PATCH  → modifier partiellement     │  Retourne JSON
  │  DELETE → supprimer                  │
  │                                      │
  ◄─────────── HTTP RESPONSE ───────────┘
       Status code + JSON body

──────────────────────────────────────────────────────────────
STATUS CODES (à retenir absolument) :
  200 OK       ← GET/PUT réussi
  201 Created  ← POST réussi (nouvelle ressource créée)
  204 No Content ← DELETE réussi
  400 Bad Request ← body invalide ou champ manquant
  401 Unauthorized ← pas de token
  403 Forbidden ← token valide mais pas les droits
  404 Not Found ← ressource inexistante
  500 Server Error ← bug côté serveur

──────────────────────────────────────────────────────────────
CONSOMMER (Python requests) :
  r = requests.get(url, headers={"Authorization": "Bearer ..."})
  r.raise_for_status()    # lève si 4xx ou 5xx
  data = r.json()         # parse le JSON en dict Python

──────────────────────────────────────────────────────────────
CRÉER (Flask) :
  @app.route('/resource', methods=['GET', 'POST'])
  def handle():
      if request.method == 'GET':
          return jsonify(data), 200
      body = request.get_json() or abort(400)
      # créer + return jsonify(new), 201

══════════════════════════════════════════════════════════════