BLAGUES API

Besoin d’une API de blagues françaises ?

#collaborative#open-source
#communautaire#français
Documentation

Qu’est ce que Blagues API ?

Blagues API est une API de blagues, rassemblant les meilleures blagues avec un total de 2524 blagues françaises.

Des blagues proposées par la communauté et catégorisées.

L’API est accessible gratuitement et rassemble sur le discord une communauté francophone.

NPM NPM

Module npm

Le module npm de Blagues-API développé en Typescript supporte l'intégralité des options présente sur l'API, il permettra d'intéragir simplement avec l'API depuis le langage NodeJs.

Installation

        
          yarn add blagues-api
        
      
        
          pnpm add blagues-api
        
      
        
          npm i blagues-api
        
      

Mise en place

        
          <script src="https://unpkg.com/blagues-api@2.1.0/dist/blagues-api.umd.js"></script>
        
      
        
          import BlaguesAPI from 'blagues-api';
        
      
        
          const BlaguesAPI = require('blagues-api');
        
      
      
        const blagues = new BlaguesAPI('VOTRE_TOKEN_ICI');
      
    

Il est fortement conseillé d'utiliser les variables d'environnement avec dotenv afin de ne pas mettre votre token dans le code source de votre projet.

Utilisation

Différentes méthodes vous sont rendues disponibles afin d'intéragir plus facilement avec l'API depuis votre projet.

Blague aléatoire

        
          const blague = await blagues.random();
        
      

A cette méthode, vous pouvez spécifier certains types que vous ne souhaitez pas recevoir.

        
          const blague = await blagues.random({
            disallow: [
              blagues.categories.DARK,
              blagues.categories.LIMIT
            ]
          });
        
      

Blague aléatoire d'une catégorie

        
          const blague = await blagues.randomCategorized(
            blagues.categories.DARK
          );
        
      

Blague à partir de son ID

Les blagues sont identifiées par un ID que vous recevez en même tant que chaque blague. Spécifiez cet identifiant en paramètre et vous l'obtiendez à nouveau.

        
          const blague = await blagues.fromId(50);
        
      

Nombres de blagues

        
          const blague = await blagues.count();
        
      

Module PyPi

Le module PyPi de Blagues-API supporte l'intégralité des options présente sur l'API, il permettra d'intéragir simplement avec l'API depuis le langage Python de manière asynchrone.

        
          pip install blagues-api
        
      
      
        from blagues_api import BlaguesAPI
      
    
      
        blagues = BlaguesAPI("VOTRE_TOKEN_ICI")
      
    

Il est fortement conseillé d'utiliser les variables d'environnement avec dotenv afin de ne pas mettre votre token dans le code source de votre projet.

Utilisation

Différentes méthodes asynchrones vous sont rendues disponibles afin d'intéragir plus facilement avec l'API depuis votre projet.

Blague aléatoire

        
          blague = await blagues.random()
        
      

A cette méthode, vous pouvez spécifier certains types que vous ne souhaitez pas recevoir.

        
          blague = await blagues.random(disallow=[BlagueType.LIMIT, BlagueType.BEAUF])
        
      

Blague aléatoire d'une catégorie

        
          blague = await blagues.random_categorized(BlagueType.DEV)
        
      

Blague à partir de son ID

Les blagues sont identifiées par un ID que vous recevez en même tant que chaque blague. Spécifiez cet identifiant en paramètre et vous l'obtiendez à nouveau.

        
          blague = await blagues.from_id(50)
        
      

Nombres de blagues

        
          blague = await blagues.count()
        
      

Module Packagist

Le module Packagist de Blagues-API supporte l'intégralité des options présente sur l'API, il permettra d'intéragir simplement avec l'API depuis le langage PHP de manière synchrone.

        
          composer require zuruuh/blagues-api
        
      
      
        use BlaguesApi\BlaguesApi;
        use BlaguesApi\Model\Joke;
      
    
      
        $blaguesApi = BlaguesApi::create('VOTRE_TOKEN_ICI');
      
    

Il est fortement conseillé d'utiliser les variables d'environnement avec un package comme symfony/dotenv par exemple, afin de ne pas mettre votre token dans le code source de votre projet.

Utilisation

Différentes méthodes vous sont rendues disponibles afin d'intéragir plus facilement avec l'API depuis votre projet.

Blague aléatoire

        
          $joke = $blaguesApi->getRandom();
        
      

A cette méthode, vous pouvez spécifier certains types que vous ne souhaitez pas recevoir.

        
          $joke = $blaguesApi->getRandom([Joke::TYPE_DARK]);
        
      

Blague aléatoire d'une catégorie

        
          $joke = $blaguesApi->getByType(Joke::TYPE_DEV);
        
      

Blague à partir de son ID

        
          $joke = $blaguesApi->getById(1234);
        
      

Nombres de blagues

        
          $joke = $blaguesApi->count();
        
      

API publique

L'API Rest est le meilleur moyen d'utiliser Blagues-API sans dépendances, en requièrera nénanmoins plus de connaissances et de prérequis.

Utilisation

Différentes routes vous sont rendues disponibles afin d'adapter l'api a votre projet. Les différents mots clés vous permettront de récupérer une blague aléatoirement dans un thème ou type de blague spécifique.

BLAGUE ALÉATOIRE
GET /api/random
BLAGUE ALÉATOIRE CATÉGORISÉ
GET /api/type/:type:/random // type: global, dev, dark, limit, beauf, blondes
BLAGUE PAR ID
GET /api/id/:id:
NOMBRES DE BLAGUES
GET /api/count

Utilisation avancée

Parfois certains types d'humour dérangent certaines personnes, hors blagues-api est une api publique qui s'est donné comme mission de convenir aux tous types d'humour. C'est pour cela que nous vous offrons la possibilité de filtrer les blagues et donc d'en retirer celles qui font partie d'une catégorie qui ne vous convient pas.

UTILISATION D'UN SEUL FILTRE
GET /api/random?disallow=dark
UTILISATION DE PLUSIEURS FILTRES
GET /api/random?disallow=dark&disallow=limit&disallow=dev

Authentification

L'api de blagues utilise un token d'authentification Bearer pour les requêtes. Vous pouvez le gérer depuis votre profil.
Les requêtes doivent toutes être effectuées via HTTPS. Tous les appels effectuées sans authentification ou en HTTP échoueront.
Si vous avez des difficultées à obtenir un certificat HTTPS, voici Certbot, un outil qui permet d'en obtenir un gratuitement !


        curl https://www.blagues-api.fr/api/random \
          -H "Authorization: Bearer VOTRE_TOKEN_ICI" \

Exemple

Voici un exemple sous forme de cas d'utilisation de l'api dans le cas où l'on souhaite récupérer une blague aléatoirement dans le répertoire toute catégorie confondue

JAVASCRIPT

      fetch('https://www.blagues-api.fr/api/random', {
        headers: {
          'Authorization': `Bearer VOTRE_TOKEN_ICI`
        }
      })
      .then(response => response.json())
      .then(data => {
        console.log(data)
        /* Expected output:
        {
          "id": 1,
          "type": "dev",
          "joke": "Un développeur ne descend pas du métro.",
          "answer": "Il libère la RAM..."
        }
        */
      })

Remerciements

Un grand merci à toute la communauté qui a contribué au projet que ça soit sur le discord ou sur le github en apportant leurs ajouts et modifications au code de l'api, mais également à tous ceux qui ont proposé leurs blagues afin d'agrandir le répertoire de l'api. Le nombre de blagues françaises continuent de grandir de jours en jours. Merci à vous !