Documentation API

Dernière mise à jour : le 20/10/2020

Getting Started

Cette API vise à de collecter et mettre gratuitement à dispositon des développeurs des contenus variés (proverbes, blagues, chuck norris facts, devinettes, fakes news, etc) pour leurs projets ou besoin de fixtures.

Demander un token

Json Web Token

Étape une

Pour utiliser l'API, vous devez au préalable demander l'obtention d'un token (Json Web Token).
La procédure est simple, rapide et sans inscription.

Étape deux

Le token envoyé par email a une validité de 48 heures.
Ce JWT doit ensuite être renseigné dans l'en-tête d'autorisation HTTP des requêtes le nécessitant.

En-tête HTTP d'autorisation :

Authorization: Bearer ‹your_token›

Étape trois

Il est possible d'automatiser la demande d'obtention d'un token afin d'en faciliter le renouvellement.
Pour cela, reportez-vous aux tableaux des routes de l'API. L'une d'elles est prévue à cet effet.

Route API token :

/api/token

Routes API

Méthode Route Paramètres Valeurs JWT Description
GET /api/get limit
category
- Min : 1 - Max : 2500
- Blague, Chuck Norris Fact, Devinette, Proverbe, Fake News
Permet de récupérer au format Json un ensemble d'enregistrements par limite et par types.
GET /api/find id identifiant de l'enregistrement recherché Permet de récupérer un enregistrement en fonction de son identifiant (id).
GET /api/random - - Permet d'obtenir une donnée aléatoire sur un échantillon restreint. Il y a une forte probabilité de redondance.
GET /api/get/random limit
category
- Min : 1 - Max : 50
- Blague, Chuck Norris Fact, Devinette, Proverbe, Fake News
Permet d'obtenir une ou plusieurs données aléatoires. Il est possible de préciser le type de données souhaitées.
POST /api/token token Json Web Token précédemment généré (expiré ou non). Permet d'obtenir un token sans passer par le formulaire d'obtention. Le token fourni a une durée de validité de 48 heures.
Il est donc possible d'automatiser l'obtention d'un token en utilisant cette route, puis en le renseignant dans l'en-tête d'autorisation HTTP pour les requêtes suivantes.

Faites connaître l'API

Vous pouvez utliser l'un de ces liens Facebook ou Twitter pour partager le site sur les réseaux sociaux.

Requête vers l'API

Exemple d'utilisation avec PHP Curl
<?php 

$url = "https://example.com/api/get";
$params = "?limit=20&category=blague";

$jwt = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1ZGRlY2VmMGE4ZTNkIiwiZXhwIjoiMjAxOS0xMS0yOSAyMDozMDo1NiIsInRlc3QiOiIrXC89In0.bZhb_fgx2IHj-M6Lbr3B-CyFoVZPzvtFzbpBsrBsKnzQFSomB-UFCTXZaNolcIWvslsvorq_YLjTgMZRpfSsRQ";

$headers = [
    "Content-Type: application/json",
    "Authorization: Bearer " . $jwt
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url . $params);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_TIMEOUT, 60);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_USERAGENT, $_SERVER["HTTP_USER_AGENT"]);
$jsonResponse = curl_exec($curl);
$response = json_decode($jsonResponse, 1);
curl_close($curl);

echo "‹pre›";
var_dump($response);
echo "‹/pre›";

?>

Response

Exemple de retour en Json
[
    {
        "id": 720,
        "content": "Comment appelle-t-on une chauve-souris qui a des cheveux ?\r\n- Une souris",
        "vote": 1717,
        "category": "Blague"
    },
    {
        "id": 719,
        "content": "Comment appelle-t-on un chat dans l’espace ?\nUn chatellite",
        "vote": 3832,
        "category": "Devinette"
    },
    {
        "id": 718,
        "content": "Pourquoi est-ce que les éoliennes n'ont pas de copain ?
        Parce qu’elles se prennent toujours des vents",
        "vote": 3791,
        "category": "Blague"
    }
]
Exemple de retour en PHP (après json_decode)
[
  {
    "id": 212,
    "content": "Un jour, Chuck Norris a fait la blague de \"j'ai volé ton nez\" à Mickael Jackson...",
    "vote": 2557,
    "categorie": "Chuck Norris Fact"
  },
  {
    "id": 112,
    "content": "Comment appelle-t-on un combat entre un petit pois et une carotte ?\nUn bon duel",
    "vote": 5664,
    "categorie": "Blague"
  }
]