Bien démarrer avec l’API pour Apprendre

Cette page n’est pas la documentation technique exhaustive de l’API. Elle sert plutôt de point d’entrée pour comprendre les usages les plus fréquents à travers des exemples.

L’API existe en deux versions afin de progresser étape par étape.

Les exemples utilisent des requêtes HTTP classiques. Chaque requête contient une méthode, une URL, parfois des headers, et parfois un corps JSON.

• GET permet de lire une ou plusieurs ressources.
• POST permet de créer une ressource.
• PUT permet de remplacer complètement une ressource.
• PATCH permet de modifier partiellement une ressource.
• DELETE permet de supprimer une ressource.
• Les données envoyées et reçues sont au format JSON.

L’API libre est accessible sans authentification. Les exemples suivants utilisent la ressource posts.

Lire la liste des posts

cURL

curl https://api-pour-apprendre.fr/api/v1/posts

JavaScript avec fetch

fetch('https://api-pour-apprendre.fr/api/v1/posts')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Erreur :', error));

Python avec requests

import requests

response = requests.get('https://api-pour-apprendre.fr/api/v1/posts')
data = response.json()

print(data)

Créer un post

La création est simulée. L’API retourne une réponse 201 Created, un header Location et la ressource créée, mais la donnée n’est pas conservée durablement.

Corps JSON à envoyer :

{
  "title": "Mon super article",
  "content": "Voici le contenu de l'article.",
  "picture": "image.jpg",
  "userId": 1
}

cURL

curl -X POST https://api-pour-apprendre.fr/api/v1/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mon super article",
    "content": "Voici le contenu de l'\''article.",
    "picture": "image.jpg",
    "userId": 1
  }'

JavaScript avec fetch

fetch('https://api-pour-apprendre.fr/api/v1/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: "Mon super article",
    content: "Voici le contenu de l'article.",
    picture: "image.jpg",
    userId: 1
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Erreur :', error));

Python avec requests

import requests

data = {
  "title": "Mon super article",
  "content": "Voici le contenu de l'article.",
  "picture": "image.jpg",
  "userId": 1
}

response = requests.post('https://api-pour-apprendre.fr/api/v1/posts', json=data)

print(response.status_code)
print(response.json())

L’API protégée nécessite un token JWT. Le token est obtenu avec la route /token, puis transmis dans le header Authorization des requêtes suivantes.

Obtenir un token JWT

Corps JSON à envoyer :

{
  "username": "nomutilisateur",
  "password": "P@ssw0rd!"
}

Les comptes de démonstration utilisent le même mot de passe : P@ssw0rd!. Voir la liste des comptes

cURL

curl -X POST https://api-pour-apprendre.fr/authapi/v1/token \
  -H "Content-Type: application/json" \
  -d '{"username": "nomutilisateur", "password": "P@ssw0rd!"}'

JavaScript avec fetch

fetch('https://api-pour-apprendre.fr/authapi/v1/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'nomutilisateur',
    password: 'P@ssw0rd!'
  })
})
.then(response => response.json())
.then(data => console.log('Token JWT :', data.token))
.catch(error => console.error('Erreur :', error));

Python avec requests

import requests

payload = {
    "username": "nomutilisateur",
    "password": "P@ssw0rd!"
}

response = requests.post('https://api-pour-apprendre.fr/authapi/v1/token', json=payload)

if response.status_code == 200:
    token = response.json().get('token')
    print("Token JWT :", token)
else:
    print("Erreur :", response.status_code, response.text)

Lire les posts avec un token

Une fois le token obtenu, il faut l’envoyer dans le header Authorization sous la forme Bearer VOTRE_TOKEN_JWT.

cURL

curl -X GET https://api-pour-apprendre.fr/authapi/v1/posts \
  -H "Authorization: Bearer VOTRE_TOKEN_JWT"

JavaScript avec fetch

const token = "votre_token_jwt";

fetch("https://api-pour-apprendre.fr/authapi/v1/posts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Erreur :", error));

Python avec requests

import requests

token = "votre_token_jwt"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get("https://api-pour-apprendre.fr/authapi/v1/posts", headers=headers)

if response.ok:
    print(response.json())
else:
    print("Erreur :", response.status_code, response.text)

Créer un post avec un token

Comme pour l’API libre, la création est simulée. La différence est que cette route nécessite un token JWT valide.

Corps JSON à envoyer :

{
  "title": "Mon super article",
  "content": "Voici le contenu de l'article.",
  "picture": "image.jpg",
  "userId": 1
}

cURL

curl -X POST https://api-pour-apprendre.fr/authapi/v1/posts \
  -H "Authorization: Bearer VOTRE_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mon post via curl",
    "content": "Contenu depuis curl",
    "picture": "https://exemple.com/image.jpg",
    "userId": 1
  }'

JavaScript avec fetch

const token = "votre_token_jwt";

fetch("https://api-pour-apprendre.fr/authapi/v1/posts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`
  },
  body: JSON.stringify({
    title: "Mon premier post",
    content: "Contenu de l'article",
    picture: "https://exemple.com/image.jpg",
    userId: 1
  })
})
.then(response => response.json())
.then(data => console.log("Post créé :", data))
.catch(error => console.error("Erreur :", error));

Python avec requests

import requests

token = "votre_token_jwt"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "title": "Mon premier post",
    "content": "Contenu de l'article",
    "picture": "https://exemple.com/image.jpg",
    "userId": 1
}

response = requests.post("https://api-pour-apprendre.fr/authapi/v1/posts", headers=headers, json=data)

if response.status_code == 201:
    print("Post créé :", response.json())
else:
    print("Erreur :", response.status_code, response.text)

Ce guide présente seulement les usages les plus courants. Pour connaître toutes les routes, les paramètres disponibles, les réponses JSON exactes et les codes HTTP possibles, utilisez les références Swagger.