01
📖 Qu'est-ce qu'une API Sémantique ?
Une API sémantique est une interface de programmation qui expose les données d'un graphe de connaissances via des endpoints REST standardisés. Contrairement aux API classiques qui renvoient du JSON brut, une API sémantique renvoie des données auto-descriptives avec des liens explicites entre les ressources.
💡 À retenir : Une API sémantique ne renvoie pas seulement des données, elle renvoie de la connaissance — des ressources identifiées, typées et reliées entre elles.
Caractéristiques clés :
- ✅ Ressources identifiées par des URI (ex: /api/speakers/emmanuel-macron)
- ✅ Données typées avec des vocabulaires standards (Schema.org, FOAF)
- ✅ Liens explicites entre ressources (HATEOAS)
- ✅ Formats standards : JSON-LD, RDF/XML, Turtle
- ✅ Interopérabilité avec l'écosystème du web sémantique
02
🎯 Pourquoi utiliser une API sémantique ?
🔍 API classique vs API sémantique
API classique :
{"id": 123, "name": "Victor Hugo", "birthYear": 1802}
API sémantique :
{
"@id": "/api/speakers/victor-hugo",
"@type": "schema:Person",
"schema:name": "Victor Hugo",
"schema:birthDate": "1802-02-26",
"schema:knows": { "@id": "/api/speakers/alexandre-dumas" }
}
Avantages :
- 📖 Auto-descriptive : les données portent leur signification
- 🔗 Navigable : exploration automatique des relations
- 🔄 Interopérable : compréhensible par n'importe quel client sémantique
- 🤖 Prête pour l'IA : structure idéale pour le RAG
- 📈 Évolutive : ajout de nouvelles relations sans rupture
03
🏗️ Architecture REST d'une API sémantique
Une API sémantique suit les principes REST avec des endpoints organisés par type de ressource.
Structure des URLs
https://api.lemondesemantique.fr/v1/
├── speakers/ # Collection des orateurs
│ ├── {id} # Orateur spécifique
│ └── {id}/speeches # Discours d'un orateur
├── speeches/ # Collection des discours
│ ├── {id} # Discours spécifique
│ └── {id}/speaker # Orateur du discours
├── search/ # Recherche
│ ├── ?q={query} # Recherche full-text
│ └── vector?q={query} # Recherche vectorielle
└── graph/ # Requêtes graphe
└── sparql # Endpoint SPARQL
Principes HATEOAS
Chaque réponse inclut des liens vers les ressources associées :
{
"@id": "/api/speeches/appel-18-juin",
"schema:author": {
"@id": "/api/speakers/charles-de-gaulle"
},
"_links": {
"self": "/api/speeches/appel-18-juin",
"speaker": "/api/speakers/charles-de-gaulle"
}
}
04
🔌 Endpoints standards
GET /api/speakers
Liste paginée des orateurs.
Paramètres : ?limit=10&offset=0&sort=name
Réponse : Collection JSON-LD d'orateurs
GET /api/speakers/{id}
Détail d'un orateur spécifique.
Exemple : /api/speakers/charles-de-gaulle
Réponse : JSON-LD de l'orateur avec liens
GET /api/speeches
Liste paginée des discours.
Paramètres : ?limit=10&offset=0&speaker_id={id}
Réponse : Collection JSON-LD de discours
GET /api/speeches/{id}
Détail d'un discours spécifique.
Exemple : /api/speeches/appel-18-juin
Réponse : JSON-LD du discours avec texte intégral
GET /api/search?q={query}
Recherche full-text dans les orateurs et discours.
Exemple : /api/search?q=résistance
Réponse : Résultats typés avec scores de pertinence
POST /api/search/vector
Recherche vectorielle sémantique.
Body : {"query": "discours sur la liberté", "top_k": 5}
Réponse : Résultats par similarité sémantique
05
📄 Formats de réponse (JSON-LD)
Notre API utilise JSON-LD comme format principal, permettant à la fois la lisibilité pour les développeurs et l'interopérabilité sémantique.
Exemple de réponse
{
"@context": {
"schema": "https://schema.org/",
"name": "schema:name",
"birthDate": "schema:birthDate",
"speeches": "schema:author"
},
"@id": "/api/speakers/victor-hugo",
"@type": "schema:Person",
"name": "Victor Hugo",
"birthDate": "1802-02-26",
"speeches": [
{ "@id": "/api/speeches/les-miserables" },
{ "@id": "/api/speeches/notre-dame-de-paris" }
]
}
Négociation de contenu
L'API supporte différents formats via le header Accept :
| Format | Header Accept |
|---|
| JSON-LD | application/ld+json |
| JSON classique | application/json |
| RDF/XML | application/rdf+xml |
| Turtle | text/turtle |
06
🔐 Authentification et sécurité
Clés API
L'API utilise une authentification par clé API (API Key) pour contrôler l'accès et la facturation.
curl -X GET https://lemondesemantique.fr/api/v1/speakers \
-H "X-API-Key: kg_live_xxxxxxxxxxxx"
Obtenir une clé API
curl -X POST https://lemondesemantique.fr/api/auth/key \
-H "Content-Type: application/json" \
-d '{"email": "developpeur@example.com", "name": "Mon Application"}'
Limites de taux (Rate Limiting)
| Plan | Requêtes/minute | Requêtes/mois |
|---|
| Gratuit | 60 | 10 000 |
| Pro | 600 | 100 000 |
| Enterprise | Illimité | Sur mesure |
⚠️ Sécurité : Ne partagez jamais votre clé API. Utilisez des variables d'environnement côté serveur.
07
🎯 Exemples concrets
1. Récupérer tous les orateurs
curl -X GET https://lemondesemantique.fr/api/v1/speakers?limit=5 \
-H "X-API-Key: votre_clé"
2. Récupérer un orateur spécifique
curl -X GET https://lemondesemantique.fr/api/v1/speakers/charles-de-gaulle \
-H "X-API-Key: votre_clé"
3. Recherche vectorielle
curl -X POST https://lemondesemantique.fr/api/v2/search/vector \
-H "Authorization: Bearer votre_clé" \
-H "Content-Type: application/json" \
-d '{"query": "discours sur la liberté", "top_k": 3}'
4. Requête SPARQL directe
curl -X POST https://lemondesemantique.fr/api/sparql \
-H "X-API-Key: votre_clé" \
-H "Content-Type: application/sparql-query" \
-d "SELECT ?nom WHERE { ?s a schema:Person ; schema:name ?nom } LIMIT 10"