Construire une API avec les fonctions Gatsby —

Vous avez probablement entendu parler des fonctions sans serveur, mais si ce n'est pas le cas, les fonctions sans serveur fournissent des fonctionnalités généralement associées aux technologies côté serveur qui peuvent être implémentées avec le code frontal sans être pris dans les infrastructures côté serveur.[19659003]Avec le code côté serveur et côté client coexistant dans la même base de code, les développeurs frontaux comme moi peuvent étendre la portée de ce qui est possible en utilisant les outils qu'ils connaissent et aiment déjà.

Limites

La coexistence est excellente. mais il y a au moins deux scénarios que j'ai rencontrés où l'utilisation des fonctions sans serveur de cette manière n'était pas tout à fait la bonne solution pour la tâche à accomplir. Ils sont les suivants :

1. Le frontal ne pouvait pas prendre en charge les fonctions sans serveur.
2. La même fonctionnalité était requise par plus d'un frontal.

Pour aider à fournir un peu de contexte, voici un exemple des points 1 et 2 nommé ci-dessus. Je maintiens un projet Open source appelé MDX Embedvous verrez sur le site de documentation que ce n'est pas un site Web de Gatsby. Il a été construit à l'aide de Storybook et Storybook à lui seul ne fournit aucune capacité de fonction sans serveur. Je voulais implémenter des contributions "Payez ce que vous voulez" pour aider à financer ce projet et je voulais utiliser Stripe pour permettre des paiements sécurisés mais sans un "backend" sécurisé. Cela n'aurait pas été possible.

En faisant abstraction de cette fonctionnalité dans un API construite avec les fonctions Gatsby J'ai pu réaliser ce que je voulais avec MDX Embed et également réutiliser la même fonctionnalité et activer la fonctionnalité « Payez ce que vous voulez » pour mon blog.

Vous pouvez en savoir plus sur la façon dont j'ai fait cela ici : Monétiser le logiciel open source avec les fonctions Gatsby et Stripe .

C'est à ce stade que l'utilisation des fonctions Gatsby peut agir comme une sorte de Back end pour le front end ou BFF 😊 et développer de cette manière s'apparente davantage au développement d'une API (Application Programming Interface).

Les API sont utilisées par le code frontal pour gérer des choses comme les connexions, le temps réel la récupération de données ou les tâches sécurisées qui ne sont pas correctement gérées par le navigateur a seul. Dans ce tutoriel, je vais expliquer comment créer une API à l'aide de Gatsby Functions et la déployer sur Gatsby Cloud.

Contrôles en amont

Les fonctions Gatsby fonctionnent lorsqu'elles sont déployées sur Gatsby Cloud ou Netlify, et dans ce tutoriel, j'expliquerai comment déployer sur Gatsby Cloud, vous devrez donc vous vous inscrire et créez d'abord un compte gratuit.

Vous aurez également besoin d'un compte GitHub, GitLab ou BitBucket, c'est ainsi que Gatsby Cloud lit votre code puis crée votre "site", ou dans ce cas, une API.[19659003] Pour les besoins de ce didacticiel, j'utiliserai GitHub. Si vous préférez aller de l'avant, le code API de démonstration terminé peut être trouvé sur mon GitHub.

Getting Started

Créez un nouveau répertoire quelque part sur votre disque local et exécutez ce qui suit dans votre Terminal. Cela configurera un package.json.

npm init -y

Dependencies

Tapez ce qui suit dans votre terminal pour installer les dépendances requises.

npm install gatsby react react -dom

Pages

Il est probable que votre API n'aura pas de "pages", mais pour éviter de voir l'avertissement par défaut de Gatsby page manquante lorsque vous visitez l'URL racine dans le navigateur, ajoutez ce qui suit à à la fois src/pages/index.js et src/pages/404.js.

//src/pages/index.js & src/pages/404.js

export default() => null;

API

Ajoutez ce qui suit à src/api/my-first-function.js.

Je vous expliquerai un peu plus tard ce que 'Access-Control-Allow-Origin', '*' signifie, mais en bref, cela garantit que vos API d'autres origines ne sont pas bloquées par CORS.

// src/api/my-first-function.js

Exporter le gestionnaire de fonction par défaut (req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  res.status(200).json({ message : 'D'accord !' });
}

Scripts

Ajoutez ce qui suit à package.json.

//package.json

...
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build"
  },
...

Démarrez le serveur de développement Gatsby

Pour lancer le serveur de développement Gatsby, exécutez ce qui suit dans votre terminal.

npm exécutez develop

Faites une demande à partir du navigateur

Avec le développement de Gatsby serveur en cours d'exécution, vous pouvez visiter http://localhost:8000/api/my-first-functionet puisqu'il s'agit d'une simple requête GETvous devriez voir ce qui suit dans votre navigateur.

{
  "message": "D'accord !"
}

Félicitations 🎉

Vous venez de développer une API à l'aide de Gatsby Functions.

Deploy

Si vous voyez la réponse ci-dessus dans votre navigateur, vous pouvez supposer que votre fonction fonctionne correctement localement, dans le les étapes suivantes, je vais expliquer comment déployer votre API sur Gatsby Cloud et y accéder à l'aide d'une requête HTTP de CodeSandbox.

Push Code To Git

Avant d'essayer de déployer sur Gatsby Cloud, vous allez devez avoir transmis votre code au fournisseur Git de votre choix.

Gatsby Cloud

Connectez-vous à votre compte Gatsby Cloud et recherchez le gros bouton violet indiquant « Ajouter un site + ».

À l'étape suivante, il vous sera demandé soit d'importer depuis un référentiel Git, soit de démarrer à partir d'un modèle, sélectionnez Importer depuis le référentiel Git et appuyez sur suivant.

Comme mentionné ci-dessus, Gatsby Cloud peut se connecter à GitHub, GitLab ou Bitbucket. Sélectionnez votre fournisseur Git préféré et cliquez sur suivant.

Avec votre fournisseur Git connecté, vous pouvez rechercher votre référentiel et donner un nom à votre site.

Une fois que vous avez sélectionné votre référentiel et nommé votre site, cliquez sur suivant.

Vous pouvez ignorer les « Intégrations » et « Configuration », car nous n'en aurons pas besoin.

Si tout s'est déroulé comme prévu, vous devriez voir quelque chose de similaire à la capture d'écran ci-dessous.

Vous verrez en haut à gauche de l'écran une URL qui se termine par gatsbyjs.ioce sera l'URL de votre API et toutes les fonctions que vous créez sont accessibles en ajoutant /api/name-of-function à la fin de cette URL.

Par exemple, la version complète déployée de my-first-function.js pour mon API de démonstration est la suivante :

API de démonstration : ma première fonction.

Test de votre API

Visiter l'URL de votre API est une chose, mais ce n'est pas vraiment la façon dont les API sont généralement utilisées . Idéalement pour tester votre API, vous devez faire une requête à la fonction depuis une origine totalement indépendante.

C'est ici où res.setHeader('Access-Control-Allow-Origin', '*'); vient à la rescousse. Bien qu'il ne soit pas toujours souhaitable d'autoriser n'importe quel domaine (site Web) à accéder à vos fonctions, pour la plupart, les fonctions publiques ne sont que cela, publiques. Définir l'en-tête de contrôle d'accès sur une valeur de * signifie que n'importe quel domaine peut accéder à votre fonction, sans cela, tout domaine autre que le domaine sur lequel l'API est hébergée sera bloqué par CORS.

Voici un CodeSandbox qui utilise my-first-function de mon API de démonstration. Vous pouvez le forker et modifier l'URL de la requête Axios pour tester votre fonction.

CodeSandbox : Ma première fonction

Getting Fancier

Envoyer une réponse de votre API qui dit message : "A ok!" n'est pas vraiment excitant, donc dans le prochain bit, je vais vous montrer comment interroger le ]API REST GitHub et créez une carte de profil personnelle à afficher sur votre propre site à l'aide de l'API que vous venez de créer, et cela ressemblera un peu à ceci.

CodeSandbox : Demo profile card

Dépendances

Pour utiliser l'API REST GitHub, vous devez installer le package @octokit/rest.

npm install @octokit/rest

Get GitHub User Raw

Ajoutez ce qui suit à src/api/get-github-user-raw.js.

//src/api/get-github-user-raw.js

importer { Octokit } depuis '@octokit/rest' ;

const octokit = new Octokit({
  auth : process.env.OCTOKIT_PERSONAL_ACCESS_TOKEN
});

exporter le gestionnaire de fonction asynchrone par défaut (req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  essayer {
    const { data } = wait octokit.request(`GET /users/{username}`, {
      nom d'utilisateur : 'PaulieScanlon'
    });

    res.status(200).json({ message : 'A ok !', utilisateur : données });
  } catch (erreur) {
    res.status(500).json({ message : 'Erreur !' });
  }
}

Jeton d'accès

Pour communiquer avec l'API REST GitHub, vous aurez besoin d'un jeton d'accès. Vous pouvez l'obtenir en suivant les étapes de ce guide à partir de GitHub : Créer un jeton d'accès personnel.

.env Variables

Pour sécuriser votre jeton d'accès, ajoutez ce qui suit à .env.development et .env.production.

OCTOKIT_PERSONAL_ACCESS_TOKEN=123YourAccessTokenABC

Vous pouvez en savoir plus sur les variables d'environnement Gatsby dans ce guide de Gatsby : Variables d'environnement15[194590].

Démarrez le serveur de développement

Comme vous l'avez fait auparavant, démarrez le serveur de développement Gatsby en tapant ce qui suit dans votre terminal.

npm run develop

Faites une demande à partir du navigateur

Avec le développement Gatsby serveur en cours d'exécution, vous pouvez visiter http://localhost:8000/api/get-github-user-rawet comme il s'agit également d'une simple requête GETvous devriez voir ce qui suit dans ton navigateur. (J'ai supprimé une partie de la réponse par souci de concision.)

{
  "message": "D'accord!",
  "utilisateur": {
    "login": "PaulieScanlon",
    "identifiant": 1465706,
    "node_id": "MDQ6VXNlcjE0NjU3MDY=",
    "avatar_url": "https://avatars.githubusercontent.com/u/1465706?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/PaulieScanlon",
    "type": "Utilisateur",
    "site_admin": faux,
    "nom": "Paul Scanlon",
    "société": "Paulie Scanlon Ltd.",
    "blog": "https://www.paulie.dev",
    "location": "Worthing",
    "email": "pauliescanlon@gmail.com",
    "louable": vrai,
    "bio": "Développeur Jamstack / Rédacteur de contenu technique (indépendant)",
    "twitter_username": "pauliescanlon",
    "created_at": "2012-02-23T13:43:26Z",
    "two_factor_authentication": vrai,
    ...
  }
}

Voici un exemple CodeSandbox de la réponse brute complète.

CodeSandbox : Raw Response

Vous verrez d'après ce qui précède qu'il y a beaucoup de données renvoyées dont je n'ai pas vraiment besoin, ce prochain bit dépend entièrement de vous car c'est votre API mais j'ai trouvé utile de manipuler la réponse de l'API GitHub un peu avant de le renvoyer à mon code frontend.

Si vous souhaitez faire la même chose, vous pouvez créer une nouvelle fonction et ajouter ce qui suit à src/api/get-github-user.js.

// src/api/get-github-user.js

importer { Octokit } depuis '@octokit/rest' ;

const octokit = new Octokit({
  auth : process.env.OCTOKIT_PERSONAL_ACCESS_TOKEN
});

exporter le gestionnaire de fonction asynchrone par défaut (req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  essayer {
    const { data } = wait octokit.request(`GET /users/{username}`, {
      nom d'utilisateur : 'PaulieScanlon'
    });

    res.status(200).json({
      message : 'D'accord !',
      utilisateur: {
        nom : données.nom,
        blog_url : data.blog,
        bio: data.bio,
        photo : data.avatar_url,
        githubUsername : `@${data.login}`,
        githubUrl : data.html_url,
        twitterUsername : `@${data.twitter_username}`,
        twitterUrl : `https://twitter.com/${data.twitter_username}`
      }
    });
  } catch (erreur) {
    res.status(500).json({ message : 'Erreur !' });
  }
}

Vous verrez d'après ce qui précède qu'au lieu de renvoyer l'objet de données complet renvoyé par l'API REST GitHub, je sélectionne uniquement les bits dont j'ai besoin, les renomme et ajoute quelques bits avant les valeurs du nom d'utilisateur et de l'URL. Cela facilite un peu la vie lorsque vous venez de rendre les données dans le code frontend.

Voici un exemple CodeSandbox de la réponse formatée.

CodeSandbox : Formatted Response

Ceci est très similaire au Profile Card CodeSandbox de plus tôt, mais j'ai également imprimé les données afin que vous puissiez voir comment chaque élément de données manipulé est utilisé.

Il convient de noter à ce stade que les quatre Les démos CodeSandbox de ce didacticiel utilisent l'API de démonstration, et aucune d'entre elles n'est construite à l'aide de Gatsby ou hébergée sur Gatsby Cloud — cool ay!

.env Variables In Gatsby Cloud

Avant de déployer vos deux nouvelles fonctions vous devrez ajouter le jeton d'accès GitHub à la section des variables d'environnement dans Gatsby Cloud.

Où aller d'ici ?

Je me suis posé cette même question. En règle générale, les fonctions sans serveur sont utilisées dans les requêtes côté client et bien que ce soit bien, je me suis demandé si elles pouvaient également être utilisées au moment de la construction pour « cuire » statiquement des données dans une page plutôt que de s'appuyer sur JavaScript qui peut ou non être désactivé dans l'utilisateur. navigateur.

…c'est donc exactement ce que j'ai fait.

Voici une sorte de tableau de bord de données qui utilise les données renvoyées par Gatsby Functions au moment de l'exécution et de la génération. J'ai construit ce site en utilisant Astro et je l'ai déployé GitHub Pages.

La raison pour laquelle je pense que c'est une excellente approche est parce que je suis capable de réutiliser la même fonctionnalité sur à la fois sur le serveur et dans le navigateur sans rien dupliquer.

Dans cette version Astro, j'ai touché le même point de terminaison exposé par mon API pour renvoyer des données qui sont ensuite soit intégrées à la page (idéal pour le référencement), soit récupérées au moment de l'exécution par le navigateur (idéal pour afficher des données en direct fraîches ou à jour). Les données à droite de la page sont demandées au moment de l'exécution à l'aide d'une requête côté client. J'ai utilisé des points de terminaison légèrement différents exposés par l'API REST GitHub pour interroger différents comptes d'utilisateurs GitHub qui créent les différentes listes.

Tout ce que vous voyez sur ce site est fourni par mon API plus complète. Je l'ai appelé : Paulie API et je l'utilise pour un certain nombre de mes sites Web.

Paulie API

Paulie API comme l'API de ce tutoriel est construit avec Gatsby mais parce que Gatsby peut agir en tant que site et API, je l'ai utilisé pour documenter le fonctionnement de toutes mes fonctions et chaque point de terminaison a sa propre page qui peut être utilisée comme un terrain de jeu interactif… n'hésitez pas à jeter un coup d'œil.

Donc, voilà, une API Gatsby Functions qui peut être utilisée par n'importe quel code côté client ou côté serveur, à partir de n'importe quel site Web construit avec n'importe quelle pile technologique. 🤯

Essayez-le et je serais très intéressé de voir ce que vous construisez. N'hésitez pas à partager dans les commentaires ci-dessous ou venez me retrouver sur Twitter : @PaulieScanlon.