Constructing An API With Gatsby Capabilities

No Comments

You’ve in all probability heard about Serverless Capabilities, however in case you haven’t, Serverless Capabilities present performance usually related to server-side applied sciences that may be carried out alongside front-end code with out getting caught up in server-side infrastructures.

With server-side and client-side code coexisting in the identical code base, front-end builders like myself can lengthen the attain of what’s doable utilizing the instruments they already know and love.

Limitations

Coexistence is nice however there are not less than two eventualities I’ve encountered the place utilizing Serverless Capabilities on this method weren’t fairly the appropriate match for the duty at hand. They’re as follows:

The entrance finish couldn’t help Serverless Capabilities.
The identical performance was required by multiple entrance finish.

To assist present some context right here’s one instance of each factors 1 and a pair of named above. I keep an Open-source mission known as MDX Embed, you’ll see from the docs web site that it’s not a Gatsby web site. It’s been constructed utilizing Storybook and Storybook by itself offers no Serverless Operate capabilities. I needed to implement “Pay what you need” contributions to assist fund this mission and I needed to make use of Stripe to allow safe funds however and not using a safe “backend” This may not have been doable.

By abstracting this performance away into an API constructed with Gatsby Capabilities I used to be in a position to obtain what I needed with MDX Embed and in addition re-use the identical performance and allow “Pay what you need” performance for my weblog.

You possibly can learn extra about how I did that right here: Monetize Open-Supply Software program With Gatsby Capabilities And Stripe.

It’s at this level that utilizing Gatsby Capabilities can act as a form of Again finish for entrance finish or BFF 😊 and creating on this method is extra akin to creating an API (Software Programming Interface).

APIs are utilized by front-end code to deal with issues like, logins, real-time information fetching, or safe duties that aren’t suitably dealt with by the browser alone. On this tutorial, I’ll clarify construct an API utilizing Gatsby Capabilities and deploy it to Gatsby Cloud.

Preflight Checks

Gatsby Capabilities work when deployed to Gatsby Cloud or Netlify, and on this tutorial, I’ll be explaining deploy to Gatsby Cloud so that you’ll must enroll and create a free account first.

You’re additionally going to want both a GitHub, GitLab or BitBucket account, that is how Gatsby Cloud reads your code after which builds your “web site”, or on this case, API.

For the needs of this tutorial, I’ll be utilizing GitHub. In the event you’d choose to leap forward, the completed demo API code might be discovered on my GitHub.

Getting Began

Create a brand new dir someplace in your native drive and run the next in your terminal. It will arrange a default package deal.json.

npm init -y

Dependencies

Kind the next into your terminal to put in the required dependencies.

npm set up gatsby react react-dom

Pages

It’s probably your API gained’t have any “pages” however to keep away from seeing Gatsby’s default lacking web page warning while you go to the foundation URL within the browser, add the next to each src/pages/index.js and src/pages/404.js.

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

export default () => null;

API

Add the next to src/api/my-first-function.js.

I’ll clarify a little bit later what ‘Entry-Management-Enable-Origin’, ‘*’ means, however briefly, it makes certain that your APIs from different origins aren’t blocked by CORS.

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

export default operate handler(req, res) {
res.setHeader(‘Entry-Management-Enable-Origin’, ‘*’);

res.standing(200).json({ message: ‘A okay!’ });
}

Scripts

Add the next to package deal.json.

//package deal.json


“scripts”: {
“develop”: “gatsby develop”,
“construct”: “gatsby construct”
},

Begin The Gatsby Improvement Server

To spin up the Gatsby growth server run the next in your terminal.

npm run develop

Make A Request From The Browser

With the Gatsby’s growth server working you’ll be able to go to http://localhost:8000/api/my-first-function, and since it is a easy GET request you need to see the next in your browser.

{
“message”: “A okay!”
}

Congratulations 🎉

You’ve simply developed an API utilizing Gatsby Capabilities.

Deploy

In case you are seeing the above response in your browser it’s secure to imagine your operate is working accurately regionally, within the following steps I’ll clarify deploy your API to Gatsby Cloud and entry it utilizing an HTTP request from CodeSandbox.

Push Code To Git

Earlier than making an attempt to deploy to Gatsby Cloud you’ll must have pushed your code to your Git supplier of selection.

Gatsby Cloud

Log into your Gatsby Cloud account and search for the large purple button that claims “Add web site +”.

Within the subsequent step, you’ll be requested to both Import from a Git repository or Begin from a Template, choose Import from Git Repository and hit subsequent.

As talked about above Gatsby Cloud can hook up with both GitHub, GitLab or Bitbucket. Choose your most well-liked Git supplier and hit subsequent.

Along with your Git supplier related, you’ll be able to seek for your repository, and provides your web site a reputation.

When you’ve chosen your repository and named your web site hit subsequent.

You possibly can skip the “Integrations” and “Setup” as we gained’t be needing these.

If all has gone to plan your ought to be seeing one thing much like the under screenshot.

You’ll see close to the highest on the left-hand aspect of the display screen a URL that ends with gatsbyjs.io, this would be the URL on your API and any capabilities you create might be accessed by including /api/name-of-function to the top of this URL.

E.g, the entire deployed model of my-first-function.js for my demo API is as follows:

Demo API: My First Operate.

Testing Your API

Visiting the URL of your API is one factor however it’s probably not how APIs are usually used. Ideally to check your API you might want to make a request to the operate from a totally unrelated origin.

It’s right here the place res.setHeader(‘Entry-Management-Enable-Origin’, ‘*’); involves the rescue. While it’s not all the time fascinating to permit any area (web site) to entry your capabilities, for probably the most half, public capabilities are simply that, public. Setting the Entry Management header to a worth of * means any area can entry your operate, with out this, any area apart from the area the API is hosted on will likely be blocked by CORS.

Right here’s a CodeSandbox that makes use of my-first-function from my demo API. You possibly can fork this and alter the Axios request URL to check your operate.

CodeSandbox: My First Operate

Getting Fancier

Sending a response out of your API that claims message: “A okay!” isn’t precisely thrilling so within the subsequent bit I’ll present you question the GitHub REST API and make a private profile card to show by yourself web site utilizing the API you simply created, and it’ll look a little bit like this.

CodeSandbox: Demo profile card

Dependencies

To make use of the GitHub REST API you’ll want to put in @octokit/relaxation package deal.

npm set up @octokit/relaxation

Get GitHub Person Uncooked

Add the next to src/api/get-github-user-raw.js.

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

import { Octokit } from ‘@octokit/relaxation’;

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

export default async operate handler(req, res) {
res.setHeader(‘Entry-Management-Enable-Origin’, ‘*’);

strive {
const { information } = await octokit.request(`GET /customers/{username}`, {
username: ‘PaulieScanlon’
});

res.standing(200).json({ message: ‘A okay!’, person: information });
} catch (error) {
res.standing(500).json({ message: ‘Error!’ });
}
}

Entry Token

To speak with the GitHub REST API you’ll want an entry token. You will get this by following the steps on this information from GitHub: Creating A Private Entry Token.

.env Variables

To maintain your entry token safe add the next to .env.growth and .env.manufacturing.

OCTOKIT_PERSONAL_ACCESS_TOKEN=123YourAccessTokenABC

You possibly can learn extra about Gatsby setting variables on this information from Gatsby: Surroundings Variables.

Begin Improvement Server

As you probably did earlier than begin the Gatsby growth server by typing the next in your terminal.

npm run develop

Make A Request From The Browser

With the Gatsby growth server working you’ll be able to go to http://localhost:8000/api/get-github-user-raw, and since this too is a straightforward GET request you need to see the next in your browser. (I’ve eliminated a part of the response for brevity.)

{
“message”: “A okay!”,
“person”: {
“login”: “PaulieScanlon”,
“id”: 1465706,
“node_id”: “MDQ6VXNlcjE0NjU3MDY=”,
“avatar_url”: “https://avatars.githubusercontent.com/u/1465706?v=4”,
“gravatar_id”: “”,
“url”: “https://api.github.com/customers/PaulieScanlon”,
“sort”: “Person”,
“site_admin”: false,
“title”: “Paul Scanlon”,
“firm”: “Paulie Scanlon Ltd.”,
“weblog”: “https://www.paulie.dev”,
“location”: “Worthing”,
“e mail”: “pauliescanlon@gmail.com”,
“hireable”: true,
“bio”: “Jamstack Developer / Technical Content material Author (freelance)”,
“twitter_username”: “pauliescanlon”,
“created_at”: “2012-02-23T13:43:26Z”,
“two_factor_authentication”: true,

}
}

Right here’s a CodeSandbox instance of the total uncooked response.

CodeSandbox: Uncooked Response

You’ll see from the above that there’s various information returned that I don’t really want, this subsequent bit is totally as much as you because it’s your API however I’ve discovered it useful to control the GitHub API response a little bit bit earlier than sending it again to my frontend code.

In the event you’d love to do the identical you would create a brand new operate and add the next to src/api/get-github-user.js.

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

import { Octokit } from ‘@octokit/relaxation’;

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

export default async operate handler(req, res) {
res.setHeader(‘Entry-Management-Enable-Origin’, ‘*’);

strive {
const { information } = await octokit.request(`GET /customers/{username}`, {
username: ‘PaulieScanlon’
});

res.standing(200).json({
message: ‘A okay!’,
person: {
title: information.title,
blog_url: information.weblog,
bio: information.bio,
picture: information.avatar_url,
githubUsername: `@${information.login}`,
githubUrl: information.html_url,
twitterUsername: `@${information.twitter_username}`,
twitterUrl: `https://twitter.com/${information.twitter_username}`
}
});
} catch (error) {
res.standing(500).json({ message: ‘Error!’ });
}
}

You’ll see from the above that somewhat than returning the entire information object returned by the GitHub REST API I pick simply the bits I want, rename them and add just a few bits earlier than the username and URL values. This makes life a bit simpler while you come to render the info within the frontend code.

Right here’s a CodeSandbox instance of the formatted response.

CodeSandbox: Formatted Response

That is similar to the Profile Card CodeSandbox from earlier, however I’ve additionally printed the info out so you’ll be able to see how every manipulated information merchandise is used.

It’s value noting at this level that every one 4 of the CodeSandbox demos on this tutorial are utilizing the demo API, and none of them are constructed utilizing Gatsby or hosted on Gatsby Cloud — cool ay!

.env Variables In Gatsby Cloud

Earlier than you deploy your two new capabilities you’ll want so as to add the GitHub Entry token to the setting variables part in Gatsby Cloud.

The place To Go From Right here?

I requested myself this very query. Sometimes talking serverless capabilities are utilized in client-side requests and while that’s wonderful I questioned in the event that they may be used at construct time to statically “bake” information right into a web page somewhat than counting on JavaScript which can or might not be disabled within the person’s browser.

…in order that’s precisely what I did.

Right here’s a form of information dashboard that makes use of information returned by Gatsby Capabilities at each run and construct time. I constructed this web site utilizing Astro and deployed it GitHub Pages.

The rationale I believe it is a nice method is as a result of I’m in a position to re-use the identical performance on each the server and within the browser with out duplicating something.

On this Astro construct I hit the identical endpoint uncovered by my API to return information that’s then both baked into the web page (nice for search engine optimization) or fetched at run time by the browser (nice for exhibiting contemporary or as much as the minute stay information).

Knowledge Dashboard

The info displayed on the left of the positioning is requested at construct time and baked into the web page with Astro. The info on the appropriate of the web page is requested at runtime utilizing a client-side request. I’ve used barely completely different endpoints uncovered by the GitHub REST API to question completely different GitHub person accounts which create the completely different lists.

All the pieces you see on this web site is supplied by my extra full API. I’ve known as it: Paulie API and I take advantage of it for a variety of my web sites.

Paulie API

Paulie API just like the API from this tutorial is constructed with Gatsby however as a result of Gatsby can act as each a web site and an API I’ve used it to doc how all my capabilities work and every endpoint has its personal web page that can be utilized as an interactive playground… be at liberty to take a look round.

So, there you’ve gotten it, A Gatsby Capabilities API that can be utilized by any client-side or server-side code, from any web site constructed with any tech stack. 🤯

Give it a go and I’d be very to see what you construct. Be at liberty to share within the feedback under or come discover me on Twitter: @PaulieScanlon.

    About Marketing Solution Australia

    We are a digital marketing company with a focus on helping our customers achieve great results across several key areas.

    Request a free quote

    We offer professional SEO services that help websites increase their organic search score drastically in order to compete for the highest rankings even when it comes to highly competitive keywords.

    Subscribe to our newsletter!

    More from our blog

    See all posts

    Leave a Comment