Forem: Amolo

Build a Realtime Serverless Trivia app using Fauna Streaming And React.js On Netlify

Amolo — Fri, 10 Dec 2021 07:08:11 +0000

INTRODUCTION

As a developer, building applications that users can interact with in real-time has become a norm for most of the developers. Most of the applications we see and interact with have at least a single real-time feature included. Real-time messaging, notifications are just two of commonly used real-time features used in applications.
While building applications it is not always clear how to achieve real time functionality, there exists a number due to many available technologies and platforms, complexity of setting up, provision of resources, scaling etc.

FAUNA

Fauna’s database is well optimized for the JamStack through its API first approach while offering powerful and useful query features through its own query language (FQL).
Fauna provides a variety of features including Streams. Using Streams, client code can subscribe to a document stored in a Fauna database and any changes to that document are immediately streamed to the client as event notifications.
With this, you can immediately interact with your users and maintain a consistent and high-level user experience, as well as keep your information and data constantly updated.
In this tutorial we will use React, Fauna and Netlify & Netlify Functions to build out a realtime serverless application.

TUTORIAL APPLICATION

As stated in our title, our application will simply allow you to post questions, following this, a user will be able to answer these questions. We will also maintain a real time leaderboard just to see how well one is stacking up against other players.

This application will:

Allow users to answer questions
Get their scores in real time

Project Setup

The recommended way to initialize a blank React app is by using create-react-app which sets up everything automatically for you.

You will be required to either have yarn or npm installed.

yarn create react-app trivia

Once this is complete,cd into the folder.
cd trivia

To quickly build out our UI, we will take advantage of Chakra UI which is a simple, modular and accessible component library that gives you the building blocks you need to quickly build your React applications.

To install Chakra UI simply use yarn or npm to do that.

yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

Basic Application Structure.

├── package.json
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   └── robots.txt
├── README.md
├── src
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── index.css
│   ├── index.js
│   ├── reportWebVitals.js
│   └── setupTests.js
└── yarn.lock

Installing Fauna

Install the faunadb npm package to allow our application to interact with our Fauna Instance.
yarn add faunadb

Setup your Fauna database.

To hold all our application’s data, we will first need to create a database.
Fortunately, this is just a single command or line of code, as shown below.
Don’t forget to create a Fauna account before continuing.
Fauna Shell
Fauna's API has various interfaces/clients, such as drivers in Javascript, Golang, Python, Java and more, a cloud console, local and cloud shells, and even a VS Code extension! For this article, we’ll start with the local Fauna Shell, which is almost 100% interchangeable with the other interfaces.

You will first be required to install the Fauna shell on your machine with the following command.
npm install -g fauna-shell

After installing the Fauna Shell with yarn, log in with your Fauna credentials using the fauna cloud-login command:

$ fauna cloud-login
For email login, enter your email below, and then your password.
For login with 3rd-party identity providers like Github or Netlify, please acquire a key from 
Dashboard > Security and enter it below instead.

Email: email@example.com
Password: **********

Now we are able to create our database.
fauna create-database trivia

Create Collections and Indexes.

To start a shell with your new database, run:
fauna shell trivia

We can now operate our database from this shell.

$ fauna shell trivia
Starting shell for database trivia
Connected to https://db.fauna.com
Type Ctrl+D or .exit to exit the shell
trivia>

In the case of our application, we will have two collections.

Questions - This will hold information about the questions.
Answers - The responses provided by the users. We will also use this collection to grade the responses.

DATA SCHEMA

Questions Collection

Each question will have the following fields

question_text - A questions eg. “Does Next.js support SSR or SSG?”
correct_answer - The correct answer to the question asked in (1) eg. “Both”
options - Distractors to the correct answer eg. [“SSR”, “SSG”]

Answers Collection

Each question response (answer) will have the following fields

question_id - a reference to the question in the questions collection.
user_id - A unique identifier for the respondent.(This value will be automatically generated and stored in the browser.)
response - The user’s response from a list of possible options.
isCorrect - A Boolean value to indicate it the answer provided is their correct (true) or incorrect (false)

Creating collections

To create our questions collection, run the following command in the shell to create the collection with the default configuration.
trivia> CreateCollection({ name: "questions" })

Next, let’s do the same for the answers’ collections.
trivia> CreateCollection({ name: "answers" })

Lastly, let’s do the same for the scores’ collections.
trivia> CreateCollection({ name: "scores" })

INDEXING OUR DATA.

Fauna highly recommends indexing your data for the purposes of searching, sorting and combining results from multiple collections.

In this application, a user will be allowed to attempt and respond to a question only once. We can enforce this constraint in our answers collection by creating an index as follows.

qna> CreateIndex({
name: "unique_question_user",
   unique: true,
   serialized: true,
   source: Collection("answers"),
   terms: [
     {
       field: ["data", "user_id"]
     },
     {
       field: ["data", "question_id"]
     }
   ]
})

SAMPLE RESPONSE

#SAMPLE RESPONSE…...
{
  ref: Index("unique_question_user"),
  ts: 1610301037970000,
  active: true,
  serialized: true,
  name: 'unique_question_user',
  unique: true,
  source: Collection("answers"),
  terms: [
    { field: [ 'data', 'user_id' ] },
    { field: [ 'data', 'question_id' ] }
  ],
  partitions: 1
}

Our second index is to enable us to quickly fetch a question based on the id.

CreateIndex({
  name: "question_by_id",
  source: Collection("questions"),
  terms: [
    {
      field: ["data", "id"]
    }
  ]
})

Lastly we will index our scores collection based on the user_id in order to allow faster retrieval and reads to this collection.

CreateIndex({
  name: "score_by_user",
  source: Collection("scores"),
  terms: [
    {
      field: ["data", "user_id"]
    }
  ]
})

SERVERLESS FUNCTIONS.

We will create two Netlify functions,
To create questions
To retrieve question data and metadata from the database.
To respond to the questions being asked and update the user’s scores.

Now let’s create our first Netlify function. To make the functions, first, we need to install Netlify CLI globally.

yarn global add netlify-cli -g

Now that the CLI is installed. We can create a key to allow our application to interact with Fauna.

CREATE A FAUNA KEY

In order for our application to send and receive data to Fauna we will need to create a key and provide its secret when performing queries.
For this application, a key with a Server Role is sufficient to create, read and delete data.
Head over to your database’s Fauna Shell and create a key using the following command.

CreateKey({
      name: "trivia-app",
      role: "server"
   })
# Example result.
# NOTE: Make sure you copy and store the secret!
# {
#   ref: Ref(Keys(), "280185139463529993"),
#     ts: 1603464278974000,
#     role: 'server',
#     secret: '<FaunaDB secret key>’',
#     hashed_secret: ...
# }

let’s create a .env file on our project root with the following fields.

netlify env:set FAUNADB_SERVER_SECRET “<FaunaDB secret key>”

Next, Let’s see how we can start with creating Netlify functions. For this, we will need to create a directory in our project root called functions and a file called netlify.toml, which will be responsible for maintaining configurations for our Netlify project. This file defines our function’s directory, build directory, and commands to execute.

[build]
command = "npm run build"
functions = "functions/"
publish = "build"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200
  force = true

We will do some additional configuration for the Netlify configuration file, like in the redirection section in this example. Notice that we are changing the default path of the Netlify function of /.netlify/** to /api/. This configuration is mainly for the improvement of the look and field of the API URL. So to trigger or call our function, we can use the path:

First, let’s make a connection file for Fauna called lib/fauna.js, returning a Fauna connection object.

const faunadb = require('faunadb');
const q = faunadb.query

const client = new faunadb.Client({
  secret: process.env.FAUNADB_SERVER_SECRET,
});

module.exports = { client, q };

We would

For our first function, we create a file: functions/createQuestion.js and add the following

const { client, q } = require("../src/lib/fauna");

exports.handler = async (event, context) => {
  try {
    let { question, answer, options } = JSON.parse(event.body);
    let results = await client.query(
      q.Create(q.Collection("questions"), {data: { question, answer, options },}),
    );
    return {statusCode: 200, body: JSON.stringify({ id: results.ref.id, data: results.data }),};
  } catch (err) {
    return { statusCode: 500, body: JSON.stringify({ error: err.toString() }) };
  }
};

For our second function, we create a file: functions/getQuestion.js and add the following.

const { client, q } = require("../src/lib/fauna");

exports.handler = async (event, context) => {
  try {
    let {id} = event.queryStringParameters
    let results = await client.query(q.Get(q.Ref(q.Collection("questions"), id )));
    return { statusCode: 200, body: JSON.stringify({ id: results.ref.id, data: results.data }),};
  } catch (err) {
    return { statusCode: 500, body: JSON.stringify({ error: err.toString() }) };
  }
};

For our last function create a functions/provideAnswer.js and add the following to the file.

// Docs on event and context https://www.netlify.com/docs/functions/#the-handler-method
const { client, q } = require("../src/lib/fauna");

exports.handler = async (event, context) => {
  try {
    let { question_id, answer, user_id } = JSON.parse(event.body);

    // ensure no missing values
    if (!(question_id && answer && user_id)) {
      return {
        statusCode: 500,
        body: JSON.stringify({
          error: "Fields question_id & answer & user_id required ",
        }),
      };
    }

    let results = await client.query(
      q.Get(q.Ref(q.Collection("questions"), question_id)),
    );
    let question = results.data;
    let isCorrect = false;
    if (question.answer === answer) isCorrect = true;
    try {
      let query = await client.query(
        q.Create(q.Collection("answers"), {
          data: {
            question_id,
            user_id,
            isCorrect: isCorrect,
            response: answer,
          },
        }),
      );
      query.data.correct = question.correct_answer;
      if (isCorrect) {
        // update the user's score if correct
        try {
          let score = await client.query(
            q.Get(q.Ref(q.Collection("scores"), process.env.LEADERBOARD_ID)),
          );
          console.log("S", score,)
          let req = await client.query(
            q.Update(q.Ref(q.Collection("scores"), process.env.LEADERBOARD_ID), {
              data: { [user_id]: ( (user_id in score.data) ? (score.data[user_id] + 10) : 10) },
            }),
          );
        } catch (error) {
            console.log(error)
            return {
                statusCode: 500, body: JSON.stringify({ error: error.toString() }),};
        }
      }
      return {
        statusCode: 200,
        body: JSON.stringify({ ref: query.ref.id, data: query.data }),
      };
    } catch (error) {
      if (error.message === "instance not unique") {
        return {
          statusCode: 500,
          body: JSON.stringify({ error: "Question is already answered" }),
        };
      }
      return {
        statusCode: 500,
        body: JSON.stringify({ error: error.toString() }),
      };
    }
  } catch (err) {
    return { statusCode: 500, body: JSON.stringify({ error: err.toString() }) };
  }
};

UI

Now that we have all our function endpoints working. We can now work on the UI for this application.

REALTIME LEADERBOARD.

For our real time leaderboard we will utilize Fauna Streaming which

Create a server-only key to be able to interact between the frontend

import {Box, Stack, useMediaQuery} from '@chakra-ui/react'
import {useEffect, useState} from 'react'
import {query as q, Client} from 'faunadb'
import rw from 'random-words'


function App() {

  let [isMobile] = useMediaQuery("(max-width:600px)");
  let [leaderboard, setLeaderboard] = useState(null)
  let client = new Client({
    secret: process.env.REACT_APP_FAUNA_CLIENT_SECRET
  })
  let stream
  const startStream = () => {
    stream = client.stream.document(q.Ref(q.Collection('scores'), process.env.REACT_APP_LEADERBOARD_ID))
    .on('snapshot', snapshot => {
      console.log("S", snapshot)
      setLeaderboard(snapshot.data)
    })
    .on('version', version => {
      console.log("V", version)
      setLeaderboard(version.document.data)
    })
    .on('error', error => {
      console.log('Error:', error)
      stream.close()
      setTimeout(startStream, 1000)
    })
    .start()
  }

  useEffect(()=>{

    if(! window.localStorage.getItem("user_id")){
      window.localStorage.setItem("user_id", `${rw()}_${Math.floor((Math.random() * 999) + 900)}` )
    }
    startStream()

  }, [])

  return (
    <div className="">
      <Stack direction={isMobile ? "column" : "column"} p="64">
        <h3>Leaderboard</h3>
        {leaderboard && Object.keys(leaderboard).map((k)=>{
          console.log(k,)
          return <><h4>{`${k} ------------ ${leaderboard[k]}`}</h4><br/></>
        })} 
      </Stack>

    </div>
  );
}

export default App;

DEPLOYING TO NETLIFY.

When deploying your site, you can easily set your environment variables with the Netlify CLI using the netlify env:set command..

Deploying to Netlify is relatively easy, all you need to do is to create a git repository.
This is a good practice as you are able to easily version control your entire application.
Next, commit your changes and push to the repository you created.
On the Netlify GUI, go to [New Site from Git]

Then select your desired project and Netlify will take care of the building, provisioning and deploying.
Once it's done, you will be provided with a URL to access your application.
Wasn’t that easy?

How to develop a fullstack Q&A app with Fauna and Next.js

Amolo — Thu, 21 Jan 2021 17:38:56 +0000

INTRODUCTION

Next.js is a powerful open source React framework. It enables features such as server-side rendering, API routes that you can use to build REST API endpoints within your Next.js app and consume it within the same app or any other app. This way, the frontend and backend can also be unified into a single codebase.
Fauna’s database is well optimized for the JamStack through its API first approach while offering powerful and useful query features through its own query language (FQL).
In this tutorial we will use Next.js and Fauna to build out a full stack Q&A application.
This application will:

Allow users to answer questions
Get their scores in real time

Project Setup.

The recommended way to initialize a Next.js app is by using create-next-app which sets up everything automatically for you.

You will be required to either have yarn or npm installed.

yarn create next-app qna

If you prefer to use npx you can run the below equivalent command.

npx create-next-app qna

Once this is complete,cd into the folder.

cd qna

Basic Application Structure

├── package.json
├── pages
│   ├── api
│   ├── _app.js
│   └── index.js
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── README.md
├── styles
│   ├── globals.css
│   └── Home.module.css
└── yarn.lock

Install the faunadb npm package to allow our application to interact with our Fauna Instance.

yarn add faunadb

Setup your Fauna database.

To store all our application’s data, we will first need to create a database.
Fortunately, this is just a single command or line of code, as shown below.
Don’t forget to create a Fauna account before continuing.

Fauna Shell

Fauna's API has various interfaces/clients, such as drivers in Javascript, Golang, Python, Java and more, a cloud console, local and cloud shells, and even a VS Code extension! For this article, we’ll start with the local Fauna Shell, which is almost 100% interchangeable with the other interfaces.

You will first be required to install the Fauna shell on your machine with the following command.

npm install -g fauna-shell

After installing the Fauna Shell with npm or yarn, log in with your Fauna credentials using the fauna cloud-login command:

$ fauna cloud-login
For email login, enter your email below, and then your password.
For login with 3rd-party identity providers like Github or Netlify, please acquire a key from 
Dashboard > Security and enter it below instead.

Email: email@example.com
Password: **********

Now we are able to create our database.

fauna create-database qna

Create Collections and Indexes.

To start a shell with your new database, run:

fauna shell qna

We can now operate our database from this shell.

$ fauna shell qna
Starting shell for database qna
Connected to https://db.fauna.com
Type Ctrl+D or .exit to exit the shell
qna>

In the case of our application, we will have two collections.

Questions - This will hold information about the questions.
Answers - The responses provided by the users. We will also use this collection to grade the responses.

Creating collections

To create our questions collection, run the following command in the shell to create the collection with the default configuration.

qna> CreateCollection({ name: "questions" })

Next, let’s do the same for the answers collections.

qna> CreateCollection({ name: "answers" })

Expected Output

DATA SCHEMA

Questions Collection

Each question will have the following fields
question_text - A questions eg. “Does Next.js support SSR or SSG?”
correct_answer - The correct answer to the question asked in (1) eg. “Both”
options - Distractors to the correct answer eg. [“SSR”, “SSG”]

Answers Collection

Each question response (answer) will have the following fields

question_id - a reference to the question in the questions collection.
user_id - A unique identifier for the respondent.(This value will be automatically generated and stored in the browser.)
response - The user’s response from a list of possible options.
isCorrect - A Boolean value to indicate it the answer provided is their correct (true) or incorrect (false)

INDEXING YOUR DATA.

Fauna highly recommends indexing your data for the purposes of searching, sorting and combining results from multiple collections.

In this Q&A app, a user will be allowed to attempt and respond to a question only once. We can enforce this constraint in our answers collection by creating an index as follows.

qna> CreateIndex({
...   name: "unique_question_user",
...   unique: true,
...   serialized: true,
...   source: Collection("answers"),
...   terms: [
...     {
.....       field: ["data", "user_id"]
.....     },
...     {
.....       field: ["data", "question_id"]
.....     }
...   ]
... })

If the index was created successfully, you should get a similar response.

#SAMPLE RESPONSE…...
{
  ref: Index("unique_question_user"),
  ts: 1610301037970000,
  active: true,
  serialized: true,
  name: 'unique_question_user',
  unique: true,
  source: Collection("answers"),
  terms: [
    { field: [ 'data', 'user_id' ] },
    { field: [ 'data', 'question_id' ] }
  ],
  partitions: 1
}

The second index we will create is to enable us get all answers by a particular user

READING AND SAVING DATA

Next.js supports multiple ways or obtaining data from the remote source eg. API or a database.
Use of getServersideProps. This props can thereafter be passed to the exported component
Using API Routes - API routes provide a straightforward solution to build your API with Next.js.Any file inside the folder pages/api is mapped to /api/* and will be treated as an API endpoint instead of a page. They are server-side only bundles and won't increase your client-side bundle size.

Now that we know about API Routes, let's create an HTTP endpoint to allow us to create a question with a simple POST request.

In the root of our application directory, in the pages/api folder, lets create a file named createQuestion.js and add the following code.

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import faunadb, {query as q} from 'faunadb';
const client = new faunadb.Client({secret: process.env.FAUNA_SECRET })

export default async (req, res) => {
   if(req.method == 'POST'){
       let {question_text, correct_answer, options } = req.body
       let results = await client.query(
           q.Create(q.Collection('questions'),
           { data : {question_text, correct_answer, options}})
       )
       console.log(results)
       res.json({ id: results.ref.id, data: results.data })
   }
 }

CREATE A FAUNA KEY

CreateKey({
      name: "qna-app",
      role: "server"
   })
# Example result.
# NOTE: Make sure you copy and store the secret!
# {
#   ref: Ref(Keys(), "280185139463529993"),
#     ts: 1603464278974000,
#     role: 'server',
#     secret: 'fnAD62i0bTBCDRjYjkcttAsY3wVyfsvynwUSqxYG',
#     hashed_secret: ...
# }

This next step is critical. Copy the secret generated and set it on your project environment by running the command below. Note that secrets are only shown once after creating keys; you’ll have to create a new key if you lose the original secret.
Create a .env.local file in the application root, and here we will place this key

# .env.local 
FAUNA_SECRET=fn……………………………….

Once you are done we can start our development server by running

$ yarn dev

SEED INITIAL QUESTIONS

Now that we have an API running at http://127.0.0.1:3000/api/createQuestion we can seed some initial questions to our database by using simple curl commands.

$ curl --location --request POST 'http://127.0.0.1:3000/api/createQuestion' \
--header 'Content-Type: application/json' \
--data-raw '{
    "question_text":"How many items in a dozen?",
    "correct_answer": "12",
    "options": ["6", "10"]
}'

$ curl --location --request POST 'http://127.0.0.1:3000/api/createQuestion' \
--header 'Content-Type: application/json' \
--data-raw '{
    "question_text":"How many bits in a byte?",
    "correct_answer": "8",
    "options": ["6", "10", "12", "16" ]
}'

Let’s also create an API endpoint that can be used to evaluate question response.

In the pages/api folder, let's create a file named evaluateResponse.js and add the following code.
This API endpoint will be available at http://127.0.0.1:3000/api/evaluateResponse and shall be invoked whenever a users response needs to be evaluated.

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import faunadb, {query as q} from 'faunadb';
const client = new faunadb.Client({secret: process.env.FAUNA_SECRET })

export default async (req, res) => {
   if(req.method == 'POST'){
       let {question_id, user_id, answer } = req.body
       if (!(question_id && answer && user_id)){
           res.json({ error: "Fields question_id & answer & user_id should be provided." })
       }
       else {
           let results = await client.query(
               q.Get( q.Ref(q.Collection('questions'), question_id)))
           let question = results.data
           let isCorrect = false
           if ( question.correct_answer === answer ){ isCorrect = true }
           try{
               let query = await client.query(
                   q.Create(q.Collection('answers'),
                       { data : { question_id, user_id, isCorrect: isCorrect, response: answer }})
               )
               query.data.correct = question.correct_answer
               res.json({ ref: query.ref.id, data: query.data }) 
           }catch(error){
               if(error.message === 'instance not unique'){
                   res.json({error: 'Question is already answered'})
               }
           }                   
   }
 }
}

We can now start working on the UI.

To create a UI quickly, we will use the react-bootstrap library and use some ready made UI components.

$ yarn add react-bootstrap bootstrap

Next, add the change the default style in the pages/_app.js file to bootstrap as shown.

// pages/_app.js

import 'bootstrap/dist/css/bootstrap.min.css'

function MyApp({ Component, pageProps }) {
 return <Component {...pageProps} />
}

export default MyApp

USERS

As noted above, we will be required to uniquely identify users sowe will generate random user ids that will be saved in the cookies.
We will use nookies to easily create and read cookie data.

yarn add nookies

getServerSideProps

Our cookies will be generated and set in the serverSideProps of our index.js.
If the cookies are available, they will be used to save user responses and also identify already attempted questions to prevent them from being loaded to the user again.

// pages/index.js
let cookies = parseCookies(context)
 if(!cookies.user_id){
   setCookie(context, 'user_id', `${rw()}${Math.floor((Math.random() * 999) + 900)}`, {
     maxAge: 7 * 24 * 60 * 60, path: '/', })
 }

In the same function, we will also retrieve a not attempted question from our questions collection in Fauna using the FQL Difference function
This will enable us to compare the entire collections of questions that are missing from a list of questions that have already been attempted by the user.
This will enable us to select the next question for the user.

We will use the following FQL query.

// pages/index.js
let query = await db.query(
   q.Difference(
     //Get All questions
     q.Select('data', q.Map(
       q.Paginate(q.Documents(q.Collection('questions'))), q.Lambda('ref', q.Var('ref')))),
     //Get  Attempted Questions
     q.Select('data', q.Map(
       q.Paginate( q.Match(q.Index('questions_attempted_by_user'), cookies.user_id)),
       q.Lambda('question_id', q.Ref(q.Collection('questions'), q.Var('question_id')))
     ))
   )
 )

Finally, update the pages/index.js file to be as below.

import Head from 'next/head'
import React, { useState, useEffect } from 'react'

import { parseCookies, setCookie, destroyCookie } from 'nookies'

import faunadb, {query as q} from 'faunadb';
const db = new faunadb.Client({secret: process.env.FAUNA_SECRET })
import rw from 'random-words'

//Bootstrap Components
import Card from 'react-bootstrap/Card'
//Import Custom Components
import Question from '../components/Question'

export default function Home( { question, auth } ) {

 let [questionId, setQuestionId] = useState(null)
 let [userId, setUserId] = useState(null)
 let cookies = parseCookies()

 return (
   <div className="container">
     <h5 style={{paddingTop:"3em"}}>🤔 Questions need answers</h5>
     <hr/>
     <Card>
       <Card.Header>
         <h5 style={{float:'right'}}>Hello {cookies.user_id}</h5>
       </Card.Header>

           <Question question={ question } />

       <p></p>
     </Card>
     <Card.Footer>
     </Card.Footer>
   </div>
 )
}

export async function getServerSideProps(context) {
 //Check for cookies and setCookie if none
 let cookies = parseCookies(context)
 if(!cookies.user_id){
   setCookie(context, 'user_id', `${rw()}${Math.floor((Math.random() * 999) + 900)}`, {
     maxAge: 7 * 24 * 60 * 60, path: '/', })
 }

 // Fetch questions
 let query = await db.query(
   q.Difference(
     //All questions
     q.Select('data', q.Map(
       q.Paginate(q.Documents(q.Collection('questions'))), q.Lambda('ref', q.Var('ref')))),
     // Attempted Questions
     q.Select('data', q.Map(
       q.Paginate( q.Match(q.Index('questions_attempted_by_user'), cookies.user_id)),
       q.Lambda('question_id', q.Ref(q.Collection('questions'), q.Var('question_id')))
     ))
   )
 )

 let question = null
 if(query.length > 0){
   let result = await db.query(q.Get(query[0]))
   question = result.data
   question.id = result.ref.id
 }

 return {
   props: {
     question,
   }, // will be passed to the page component as props
 }
}

Then create a components folder and in the ./components/Question.jsx add the following code for our question’s component.

import React, {useState} from 'react'
import Card from 'react-bootstrap/Card'
import Form from 'react-bootstrap/Form'
import Button from 'react-bootstrap/Button'
import { parseCookies } from 'nookies'
import {useRouter} from 'next/router'
import Alert from 'react-bootstrap/Alert'

export default function Question({ question }){

   let [answer, setAnswer ] = useState(null)
   let [evaluated, setEvaluated] = useState(null)

   let router = useRouter()
   let cookies = parseCookies()
   let user_id = cookies.user_id

   let submitResponse = async () => {
       let request = await fetch('/api/evaluateResponse', {
           headers:{ 'Content-Type': 'application/json'},
           body: JSON.stringify({ question_id: question.id, user_id: user_id, answer: answer}),
           method: "POST",
       })
       let response = await request.json()
       setEvaluated(response.data)
       setTimeout(function(){
           setEvaluated(null)
           router.push('/')}, 2500)
   }

   return(
       <>
       {evaluated ? <Alert variant="info">You answer was {evaluated.isCorrect ?
           "correct": `wrong. Correct answer is ${evaluated.correct}`}</Alert> : <></>}
       {question ? <Card.Body>
           <h4>{question.question_text}</h4>
           <hr/>
           {(question.options.concat(question.correct_answer)).map((answer, idx)=>{
               return ( <h4 key={idx}>
                           <Form.Check type="radio"
                               onChange={e => {setAnswer(e.target.value)}}  value={answer} name="options" label={answer} />
                        </h4> )
           })}
           <div className="container">
               {   answer ?
                   <Button className="col-sm-12 col-lg-12 col-md-12" variant="warning" onClick={submitResponse}>Answer</Button> :
                   <Button className="col-sm-12 col-lg-12 col-md-12" variant="warning" disabled>Answer</Button>
               }
           </div>
       </Card.Body> : <h4>You have answered all available questions.</h4>
       }
       </>
   )
}

When we run the dev server

yarn dev

When you visit http://localhost:3000 you will be greeted with the questions page as shown below.

Deploy to Vercel

To deploy our app to Vercel, we first need to install the Vercel CLI by running the following command.

npm i -g vercel

Ensure you have a Vercel account, or head over to vercel.com to create one.
Once registered, run the following command to login to the CLI with your account.

vercel login

Follow the prompts to confirm your email.
Once you successfully login, run the following command to setup and deploy the app to Vercel.

vercel

$ vercel
Vercel CLI 20.1.1
? Set up and deploy “~/x/qna”? [Y/n] y
? Which scope do you want to deploy to? Bryan
? Link to existing project? [y/N] n
? What’s your project’s name? qna
? In which directory is your code located? ./
Auto-detected Project Settings (Next.js):
- Build Command: `npm run build` or `next build`
- Output Directory: Next.js default
- Development Command: next dev --port $PORT
? Want to override the settings? [y/N] n

🔍  Inspect: https://vercel.com/amolo/qna/ikxz9cpa2 [5s]
✅  Preview: https://qna.amolo.vercel.app [copied to clipboard] [48s]
📝  To deploy to production, run `vercel --prod`

Next we will need to add the FAUNA_SECRET environment variable to allow our app interact with Fauna.

vercel env add

Follow the prompts as shown below

$ vercel env add
Vercel CLI 20.1.1
? What’s the name of the variable? FAUNA_SECRET
? What’s the value of FAUNA_SECRET? [hidden]
? Add FAUNA_SECRET to which Environments (select multiple)? Production, Preview,
 Development
✅  Added Environment Variable FAUNA_SECRET to Project qna [2s]

Finally we can deploy our app with

vercel  --prod

$ vercel --prod
Vercel CLI 20.1.1
🔍  Inspect: https://vercel.com/amolo/qna/co2hv7ces [2s]
✅  Production: https://qna-seven.vercel.app [copied to clipboard] [35s]

Your app is now live.
You can visit the demo on https://qna-seven.vercel.app

Conclusion

For this tutorial, we are able to see how fast it can be to develop a full stack application with Fauna and Next.js.
Next.js provides a highly productive, powerful and fast framework that we can use to develop both backend and frontend components of our full stack app.
Secondly, we can see how Fauna is indeed a powerful database; with a powerful FQL, which supports complex querying and integration with the serverless and JAMStack ecosystem through its API first approach. This enables developers to simplify code and ship faster.

I hope you find Fauna to be exciting, like I do, and that you enjoyed this article. Feel free to follow me on Twitter @theAmolo if you enjoyed this!

All code written for this tutorial can be found in the following Github Repo

How to create a job board with Fauna and Redwood.js

Amolo — Thu, 03 Dec 2020 14:57:41 +0000

INTRODUCTION

Redwood.js & Full Stack

Redwood is an opinionated, full-stack, serverless web application framework that enables developers to build and deploy Jamstack applications with ease.
One of the main Redwood’s philosophies is power in standards, so it makes decisions about which technologies to use, organizing your code into files, and naming conventions.

Fauna

Fauna is a powerful and fully featured serverless database. With a web-native GraphQL interface that supports custom business logic, consistent data and total freedom from database operations since its fully managed.

By using Fauna in this application’s architecture, we are able to simplify code, reduce costs and ship faster.

The Application.

In this tutorial, we will be developing a simple job board.

Getting started.

We'll use yarn (yarn is a requirement) to create the basic structure of our app:

yarn create redwood-app ./job-board

You'll have a new directory “job-board” containing several directories and files. Change to that directory.

Redwood File Structure

Let's take a look at the files and directories that were created for us (config files have been excluded for now):

In the web folder.

In the api folder.

From the above structure, it's clear how Redwood makes decisions for you about which technologies to use, how to organize your code into files, and how to name things.
It can be a little overwhelming to look at everything that’s already been generated for us. The first thing to pay attention to is that Redwood apps are separated into two directories:

web directory for the application frontend.
api for the backend

Setting Up Fauna.

Create Fauna Account
To hold all our application’s data, we will first need to create a database. Fortunately, this is just a single command or line of code, as shown below. Don’t forget to create a Fauna account before continuing!

NOTE:
Fauna offers a generous free tier for you not only to test your app but you can also use this to build your small hobby apps.

Fauna Shell

Fauna’s API has many interfaces/clients, such as drivers in JS, GO, Java and more, a cloud console, local and cloud shells, and even a VS Code extension! For this article, we’ll start with the local Fauna Shell, which is almost 100% interchangeable with the other interfaces.

npm install -g fauna-shell

After installing the Fauna Shell with npm, log in with your Fauna credentials:

$ fauna cloud-login

Email: email@example.com
Password: **********

Creating the Database

Now we are able to create our database.
To create your database enter the fauna create-database command and give your database name.

fauna create-database job-board

To start the fauna shell with our new database we’ll enter the fauna shell command followed by the name of the database.

fauna shell job-board

GraphQL on Fauna.

One of the many great features of Fauna is its first class support for GraphQL.
One big advantage of using GraphQL on Fauna is that it allows you to define a schema and it will do its magic in the background to ensure your entities, collections and their relationships are created. All you need to provide is a schema.

Writing Schema.

We will use the below schema for our application.
Create a file in the your directory and name it job-board-schema.gql

type Listing {
 title: String!,
 description: String!,
 location: String!
 company: String!
}

type Query{
 listings: [Listing]
}

Importing Schema.

On your database page on Fauna, go to the GraphQL tab on the left side bar. You will see a page similar to the one above.

Click on “Import Schema” then select the sample schema from your application directory.

This will automatically create the required collection, FQL queries to fetch and create data together with indexes that will be required for query and mutation capabilities.

Testing the schema (Graphiql) and Writing Queries.

Now that we have successfully imported our GraphQL schema definition, we can now test if our GraphQL API is working by running the following mutations to seed initial data to our database.

mutation {
  createListing(data:{
    title: "Python Developer",
    description: "Experience Python developer with experience in Flask and FaunaDB",
    location: "Kisumu",
    company: "Dala Systems"
  }),
  {
    _id
    title
  }
}

Then

mutation {
  createListing(data:{
    title: "Node.js Developer",
    description: "Outstanding Node.js with 3+ Years experience in developing serverless apps",
    location: "Cape Town",
    company: "Sugar Systems"
  }),
  {
    _id
    title
  }

If the above mutations execute successfully, they should return the _id and title of the newly created job listing.

Moreover, you can further confirm this by running the following query should list all the available jobs posted to the collection.

query {
  listings {
    data{
      title
      description
      company
    }
  }
}

4. Setting up Redwood to work with Fauna.

When generating the project using yarn, the default database is an instance of the PrismaClient. Since Prisma doesn’t support Fauna currently, we will make use of graphql-request to query the GraphQL API we created above.

yarn add graphql-request graphql

In the api/src/lib/db.js add the following code.

import { GraphQLClient } from 'graphql-request'

export const request = async (query = {}) => {
  const endpoint = 'https://graphql.fauna.com/graphql'

  const graphQLClient = new GraphQLClient(endpoint, {
    headers: {
      authorization: 'Bearer <FAUNADB_KEY>'
    },
  })
  try {
    return await graphQLClient.request(query)
  } catch (error) {
    console.log(error)
    return error
  }}

To access our Fauna database through the GraphQL endpoint we’ll need to set a request header containing our database key as provided by Fauna.

Obtaining your Fauna database key.

Head over to your database’s Fauna Shell and create a key using the following command.

CreateKey({
      name: "redwood-app",
      role: "server"
   })

# Example result.
# NOTE: Make sure you copy and store the secret!
# {
#   ref: Ref(Keys(), "280185139463529993"),
#     ts: 1603464278974000,
#     role: 'server',
#     secret: 'fn…………………………………………………..',
#     hashed_secret: ...
# }

After this you will also be required to create a api/src/graphql/listings.sdl.js file and add the following contents.

import gql from 'graphql-tag'

export const schema = gql`

type Listing {
  title: String!,
  description: String!,
  location: String!,
  company: String!
}

type ListingsPage {
  data: [Listing]
}

type Query{
  listings: ListingsPage
  jobs: [Listing]
}
`

Redwood.js Services

In our api/src/services directory we'll create a listings directory with a file called listings.js. Services are where Redwood centralizes all business logic. These can be used by your GraphQL API or any other place in your backend code. The listings function is querying the Fauna GraphQL endpoint and returning our posts data so it can be consumed by our ListingsCell.

// api/src/services/listings/listings.js

import { request } from 'src/lib/db'
import { gql } from 'graphql-request'

export const listings = async () => {
 const query = gql`
 {
   listings{
     data {
       title
       description
       location
       company
     }
 }
 }
 `

 const data = await request(query, 'https://graphql.fauna.com/graphql')
 return data['listings']
}

5. Writing the application.

Now that our application is already set up, we can start creating pages. We’ll use the generate page command to create a home page and a folder to hold that page. The commands for generating a page is ‘generate’ although we can use g to save some typing.

yarn rw g page home /

On this page we will list all available job listings posted in our Fauna collection.

Redwood.js Cells.

In Redwood.js, cells provide a simpler and more declarative approach to data fetching. They contain the GraphQL query, loading, empty, error, and success states, each one rendering itself automatically depending on what state your cell is in.
Create a folder in web/src/components called ListingsCell and inside that folder create a file called ListingsCell.js.
Inside that file add the following code.

// web/src/components/ListingsCell/ListingsCell.js

export const QUERY = gql`
 query LISTINGS {
   listings {
     data {
       title
       description
       location
       company
     }
   }
 }
`

export const Loading = () => <div>Loading Job Listings...</div>
export const Empty = () => <div>No Job Listings yet!</div>
export const Failure = ({ error }) => <div>Error: {error.message}</div>

export const Success = ({ listings }) => {
 const {data} = listings
 return (
   <div style={{maxWidth:"50%", margin:"auto"}}>
     {data.map(listing => (
       <>
       <div style={{border: "black 1pt solid", padding: ".7em"}}>
       <h4>{listing.title}</h4>
       <p>{listing.description}</p>
       <p>Organization: {listing.company} <br/>
       Location: {listing.location}</p>
       </div>
       </>
     ))}
   </div>
 )
}

Now in our web/src/pages folder we will see a HomePage folder with a file named HomePage.js.

In this file add the following code.

import ListingsCell from 'src/components/ListingsCell'

const HomePage = () => {
 return (
   <>
     <h1>Fauna Redwood.js Job Board</h1>
     <ListingsCell />
   </>
 )
}

export default HomePage

6. Testing App.

To preview if our app is working, we will need to run the following command in your terminal.

yarn rw dev

Then visit http://localhost:8910/ you should be greeted with a preview as shown below.

7. Deploying to Netlify.

Redwood was created to make full-stack web apps easier to build and deploy on the Jamstack. Now that we have seen what building a Redwood app is like, how about we try deploying one?
To make the app ready for deployment, we can take advantage of the Redwood generator. To do this, run the following code.

yarn rw g deploy netlify

This creates a file at /netlify.toml which contains the commands and file paths that Netlify needs to know about to build a Redwood application.

Next, we need to ensure our application is committed and pushed to Github.

git init
git add .
git commit -m 'First commit'
git remote add origin ...
git push -u origin master

After this, we are going to link Netlify directly to our git repo so that a simple push to main will re-deploy our entire application.

In your Netlify account select the option “New Site from Git” and follow the prompts to link your repo and it should deploy automatically.

At this point, you will discover that the posts aren’t loading. The reason for this is the lack of a Fauna key in your Netlify environment. To resolve this, go to your application page.

In the Build & deploy tab, scroll to the Environment section and add your Fauna database key with the key FAUNA_KEY and save.

Now your application is live and working. When you visit the application URL you should see a similar page.

Upon loading, you will see the job listings.

Conclusion

From this tutorial, we can see how simple it can be to develop a full stack application with Redwood and Fauna which is indeed a powerful database; with a web-native GraphQL interface, which supports custom business logic and integration with the serverless ecosystem. This enables developers to simplify code and ship faster.

Combined together with Netlify, we can have a truly serverless and fully managed full stack application. The advantages we get from this architecture is a great boost to productivity as we can focus on implementing features that make our application and UX unique, instead of getting hung up on the DevOps of servers and databases.

I hope you find Fauna to be exciting, like I do, and that you enjoyed this article. Feel free to follow me on Twitter @theAmolo if you enjoyed this!

BONUS:
All code written for this tutorial can be found in the following Github Repo

How to Build Microservices with Fauna, Python/Flask and Deploy to Vercel.

Amolo — Wed, 28 Oct 2020 19:56:55 +0000

INTRODUCTION.

Microservices, this term is mostly used as a reference to the microservices architecture which is an architectural style that structures an application as a collection of loosely-coupled services.
Each of these services is responsible for a discrete task and can communicate with other services through simple APIs to solve a larger complex business problem.

One big advantage of using this approach is that the constituent services can be developed, deployed and maintained independent of each other. Therefore you are able to easily and gradually grow your application.

FAUNA.

For microservices, Fauna has a number of great features that are well suited for this architecture e.g. multi-tenancy which enables developers to create child databases inside the main database that are isolated from each other. This way you can keep data for each service or microservice separately and securely from the others.

In addition to the features above, Fauna also provides us with a powerful and fully-managed database. This way we don’t need to worry about database correctness, sharding, provisioning, latency, or scaling our database. This is why it’s many times referred to as the truly serverless database.

By including Fauna and Vercel in our application stack, we are able to have a fully managed serverless stack. We can make changes to the application and simply do a git push. Vercel will take care of computing resource provisioning while Fauna will provide us with a fully managed database.

This is a tremendous boost to developer productivity as we are able to focus only on what makes our app unique without wasting a lot of time doing the provisioning and maintenance tasks ourselves.

THE APPLICATION.

In this tutorial, we will be creating two microservices for a classic e-commerce backend to enable the following in our application.

Product Catalog Management.
Product Reviews Management.

These microservices will allow us to create a new product entry, edit / update an existing product’s details, delete a product entry, create a product review, edit/update an existing product review, and delete a product review.

We will take advantage of the Flask Web Framework which is a very powerful Python micro framework to expose our microservices as a web API. Compared to other frameworks such as Django, Flask is lightweight and allows you a lot of flexibility while developing web applications.

CREATING YOUR DATABASE ON FAUNA.

Fauna Shell

Fauna's API has many interfaces/clients, such as drivers in JS, GO, Java and more, a cloud console, local and cloud shells, and even a VS Code extension! For this article, we’ll start with the local Fauna Shell, which is almost 100% interchangeable with the other interfaces.

npm install -g fauna-shell

After installing the Fauna Shell with npm, log in with your Fauna credentials:

$ fauna cloud-login

Email: email@example.com
Password: **********

Now we are able to create our database.

fauna create-database e-commerce

CREATE COLLECTIONS.

Now that we have our database created, it's time to create our collections.

In Fauna, a database is made up of one or more collections. The data you create is represented as documents and saved in a collection. A collection is like an SQL table.
Or rather, a collection, is a collection of documents.
A fair comparison with a traditional SQL database would be as below.

For our two microservices, we will create two collections in our database. Namely.

products collection.
reviews collection.

To start an interactive shell for querying our new database, we need to run:

fauna shell e-commerce

We can now operate our database from this shell.

$ fauna shell e-commerce
Starting shell for database my_app
Connected to https://db.fauna.com
Type Ctrl+D or .exit to exit the shell
e-commerce>

To create our products collection, run the following command in the shell to create the collection with the default configuration.

e-commerce> CreateCollection({ name: "products" })

Next, let’s do the same for the reviews collections.

e-commerce> CreateCollection({ name: "reviews" })

INDEXING YOUR DATA.

Fauna highly recommends indexing your data for the purposes of searching, sorting and combining results from multiple collections (typically called “joins”).
In the context of our application, “search” indexes will allow us to get all reviews for a particular product or all products under a specific category. Search results are based on an index’s “terms” attribute, where we specify the array path to a document’s field, which must match a search argument to be included in a set of results.

We will create the following indexes.

products_by_category - To allow us to retrieve products by their category
reviews_by_product - To allow us to retrieve a review based on its product.

To create the products_by_category index, run the following command in a fauna shell for our database.

CreateIndex({
  name: "products_by_category",
  source: Collection("products"),
  terms: [
    {
      field: ["data", "categories"]
    }
  ]
})

Next, do the same for the reviews_by_product index.

CreateIndex({
  name: "reviews_by_product",
  source: Collection("reviews"),
  terms: [
    {
      field: ["data", "product"]
    }
  ]
})

While using Fauna, it is generally ideal to write your read queries to go through your indexes, especially for performance purposes.

PROJECT SETUP

To quickly bootstrap our application and its structure we will take advantage of this Flask Template for Fauna.
Clone the Github repository containing the template using the snippet below.

git clone https://github.com/brianraila/faunadb-hipflask.git ecommerce-tutorial

Once this is done, cd into the directory and install all required dependencies.

cd e-commerce-tutorial
pip3 install -r requirements.txt

This will install flask and faunadb-python, along with any other required dependencies.

CREATE A FAUNA KEY

In order for our application to send and receive data to Fauna we will need to create a key and provide its secret when performing queries.

For this application, a key with a Server Role is sufficient to create, read and delete data.
Head over to your database’s Fauna Shell and create a key using the following command.

CreateKey({
      name: "flask-app",
      role: "server"
   })

# Example result.
# NOTE: Make sure you copy and store the secret!
# {
#   ref: Ref(Keys(), "280185139463529993"),
#     ts: 1603464278974000,
#     role: 'server',
#     secret: 'fnAD62i0bTBCDRjYjkcttAsY3wVyfsvynwUSqxYG',
#     hashed_secret: ...
# }

export FAUNA_SECRET=the-fauna-secret-you-copied

PROJECT OVERVIEW

The cloned repository has the directory structure shown below.

The only bit we are going to focus on is the app folder. This folder contains the following files and folders.

WRITING THE MICROSERVICES.

Using Fauna’s native API, The Fauna Query Language (FQL), we can satisfy all of our CRUD needs when resolving the various REST paths of our microservices.
Given FQL’s functional programming design, queries ranging from the simplest CRUD to complex transactions involving precise data manipulation and retrieval, are easily achievable. Note that FQL and query executions are transactional, meaning no changes are committed if an error occurs or conditions aren’t met; this behavior is particular useful for critical business logic, eg. avoiding over-ordering of limited inventory.

This template takes advantage of Flask blueprints which allow us to make our applications as modular as possible. This will help us in separating our microservices and their views into individual and independent components of the entire application.

For our two services, we will create two files in the app/services folder.

app/services/products.py - for the Product Catalog Microservice.
app/services/reviews.py - for Product Reviews Microservice.

Eventually, we will have the following endpoints.

Products Microservice.

As described above, this microservice will be responsible for creating , reading , updating and deleting products for our application.

Add the following code to the products microservices file.
[./app/services/products.py]

from flask import (
   Blueprint, render_template, jsonify, request
   )
from app.db import client

# Fauna Imports
from faunadb import query as q
from faunadb import errors
from faunadb.objects import Ref

bp = Blueprint('products', __name__, url_prefix='/products')

@bp.route("", methods=["GET", "POST"])
def products():
   if request.method == "GET":
       category = request.args.get("category") or None

       if category:
           # Executes the provided FQL expression.
           data = client.query( 
              # Maps over an array or FQL page and calls an expression/lambda on each item.
              # In this case, we are calling q.get on each item returned from the 2nd parameter’s q.paginate.
               q.map_(
                   # q.get takes a document’s Ref and retrieves the entire document.
                   # Refs are similar to primary/foreign keys and serve as unique pointers to documents.
                   lambda x: q.get(x),
                   # q.index returns the Ref for an index. Note that all entities in FaunaDB are documents and have Refs.
                   # q.match takes the ref of an index, along with search parameters, and returns something called a SetRef.
                   # Finally, q.paginate takes a SetRef and returns a page with iterable data.
                   q.paginate(q.match(
                       q.index("products_by_category"), category)))   
                   )
           response = [i["data"] for i in data["data"]]
           for i in range(0, len(response)):response[i]['id'] = str(data["data"][i]["ref"].id())
           return jsonify(data=response)



       data = client.query(
           q.map_(
               lambda x: q.get(x), q.paginate(q.documents(q.collection("products")))
           )
       )
     # We use q.documents to return all document refs in a collection
       response = [i["data"] for i in data["data"]]
       for i in range(0, len(response)):response[i]['id'] = str(data["data"][i]["ref"].id())
       return jsonify(data=response)

   elif request.method == "POST":

       request_data = request.get_json()
       response = client.query(
           q.create(q.collection("products"), {"data": request_data})
       )
     # FQL: q.create(collection, data_to_create) - Used to create a new document in a collection
       return jsonify(id=response["ref"].id())


@bp.route("/<id>", methods=["GET", "PUT", "DELETE"])
def product(id):
   if request.method == "GET":
       try:
           response = client.query(q.get(q.ref(q.collection("products"), id)))
           return jsonify(data=response["data"])

       except errors.NotFound:
           return jsonify(data=None)

   elif request.method == "PUT":
       # FQL: update a products document
       try:
           response = client.query(
               q.update(
                   q.ref(q.collection("products"), id), {"data":request.get_json()}
               )
           )
      # FQL: we use q.update(doc_ref, data) to update an existing document in a collection 
       except Exception as e:
           return jsonify(error=str(e))

   elif request.method == "DELETE":
       # FQL: delete a product document matching the specified product Ref.
       try:
           response = client.query(q.delete(q.ref(q.collection("products"), id)))
           return response
       except Exception as e:
           return jsonify(error=str(e))

Reviews Microservice.

As described above, this microservice will be responsible for creating, reading, updating and deleting reviews for our application.

Add the following code to the reviews microservices file.
[./app/services/reviews.py]

from flask import (
   Blueprint, render_template, jsonify, request
   )
from app.db import client

# Fauna Imports
from faunadb import query as q
from faunadb import errors
from faunadb.objects import Ref

bp = Blueprint('reviews', __name__, url_prefix='/reviews')

@bp.route("", methods=["GET", "POST"])
def reviews():
   if request.method == "GET":
       product = request.args.get('product')
       if product:
      # FQL: Query the reviews_by_product index for products matching the category using the match function.
           data = client.query(
               q.map_(
                   lambda x: q.get(x), q.paginate(q.match(
                       q.index("reviews_by_product"), product))) 
                   )
           response = [i["data"] for i in data["data"]]
           for i in range(0, len(response)):response[i]['id'] = str(data["data"][i]["ref"].id())
           return jsonify(data=response)

       data = client.query(
           q.map_(lambda x: q.get(x), q.paginate(q.documents(q.collection("reviews"))))
       )
       response = [i["data"] for i in data["data"]]
       for i in range(0, len(response)):response[i]['id'] = str(data["data"][i]["ref"].id())
       return jsonify(data=response)

   elif request.method == "POST":

       request_data = request.get_json()
       response = client.query(
           q.create(q.collection("reviews"), {"data": request_data})
       )
       return jsonify(id=response["ref"].id())

@bp.route("/<id>", methods=["GET", "PUT", "DELETE"])
def review(id):
   if request.method == "GET":
       # Retrieve a reviews document that matched a specified id.
       try:
           response = client.query(q.get(q.ref(q.collection("reviews"), id)))
           return jsonify(data=response["data"])

       except errors.NotFound:
           return jsonify(data=None)

   elif request.method == "PUT":
       # FQL: update a reviews document that match the id specified
       try:
           response = client.query(
               q.update(
                   q.ref(q.collection("reviews"), id), {"data":response.get_json()}
               )
           )
       except Exception as e:
           return jsonify(error=str(e))

   elif request.method == "DELETE":
       # FQL: delete a reviews document that match the id specified
       try:
           response = client.query(q.delete(q.ref(q.collection("reviews"), id)))
           return response
       except Exception as e:
           return jsonify(error=str(e))

Register Services.

Our application has it’s microservices written as blueprints. In Flask, we will need to register each of these blueprints to make them available to our application.
To do this, add the following code to the ./app/init.py file

[./app/init.py]

import os
from flask import Flask

def create_app():

   app = Flask( __name__, instance_relative_config=True,)
   app.config.from_mapping( SECRET_KEY=os.environ.get('SECRET_KEY') or 'you-never-guess',)

   from app.services import index, products, reviews

   app.register_blueprint(index.bp)
   app.register_blueprint(products.bp)
   app.register_blueprint(reviews.bp)

   return app

app = create_app()

TESTING.

To run our application in testing and debug mode run the following in the application directory.

python3 run.py

Since our microservices exist as REST API endpoints that are decomposed by paths and routes, if you’re interested, you can make use of Postman to test how well they work. Here’s a Postman Collection you can use to test the various routes.

The following Github repo has sample data you can use to test each of the endpoints.

DEPLOYING TO VERCEL.

Vercel allows for configuration files to describe how we’d like our microservices deployed.
The template we used comes with one by default so you will not need to do so; below is what it looks like.

[./vercel.json]

{
    "version": 2,
    "builds": [
        {
            "src": "./index.py",
            "use": "@vercel/python"
        }
    ],
    "routes": [
        {
            "src": "/(.*)",
            "dest": "/"
        }
    ]
}

To deploy our app to Vercel, we first need to install the Vercel CLI by running the following command.

npm i -g vercel

Ensure you have a Vercel account, or head over to Vercel.com to create one.

Once registered, run the following command to login to the CLI with your account.

vercel login

Follow the prompts to confirm your email.
Once you successfully login, run the following command to setup and deploy the app to Vercel.

vercel

You will receive a similar prompt screen.

Since Vercel still doesn’t know your FAUNA SECRET KEY, you will get an error while using the app. To rectify this, add the secret key to your Vercel environment as follows.

vercel env add

Follow the prompts as shown below.

Add the key for the production environment and if you wish, the dev environment.

Now redeploy your app using

vercel --prod

And now your application should be live.
You can preview your app by visiting the link provided by Vercel.

CONCLUSION

From the tutorial, we can see how easy it is to get started with Fauna for our microservices. Fauna is indeed a powerful database; through FQL we have a flexible query language to support a myriad of queries and data models. It also comes with great features suited for microservices, like multi-tenancy and granular permissions.

Combined together with Vercel, we can have a truly serverless and fully managed microservice architecture. This is a great boost to productivity as we can focus on implementing features that make our application and UX unique, instead of getting hung up on the DevOps of old-school servers and databases.

I hope you find Fauna to be exciting, like I do, and that you enjoyed this article. Feel free to follow me on Twitter @theAmolo if you enjoyed my perspective!

BONUS:
All code written for this tutorial can be found in the following Github Repo

How to build your own URL Shortener with FaunaDB

Amolo — Mon, 17 Aug 2020 07:08:56 +0000

Introduction.

FaunaDB provides you with a fully managed database, therefore you don’t have to worry about provisioning, patching and monitoring.
Therefore, using FaunaDB is a great way for developers to increase their productivity.
This tutorial demonstrates how to get started with GraphQL with FaunaDB. In this tutorial will be building a simple URL shortening app. With this app you can test basic create and read functionality.

The Application

The final application will allow us do the following.

Enter a long unreadable/readable link and turn it into a shorter less scary link.
Direct you to the original URL upon visiting the generated short URL. Pretty much the basic features of a URL shortener such as Bitly.

Pre-requisites.

A FaunaDB Account
A Netlify Account.

Application Architecture/Stack.

The application we build in this tutorial will model concepts of the JAMStack.

Why JAMStack?
JAMStack is a relatively new way of building websites and apps that delivers a better performance, higher security, lower cost of scaling, and a better developer experience.

For the frontend, we will be using React to build our web page which will be served on Netlify. One of the biggest advantages of this is that Netlify will automatically build, deploy and serve your application for you. This site will be served from their CDNs, hence you are assured of extremely fast site response times.

As in the case of many applications, we will need to store our data. In this case, we will make use of FaunaDB. Due to the advantages of FaunaDB we are able to focus on the app and let the Fauna team worry about provisioning, patching and monitoring tasks.

In order to securely access our database without sharing our Fauna API keys we will use Netlify Functions as an intermediary to interact.

TIP:
Adopting an architecture similar to the one above allows you to focus on what really matters. The features you need for your application’s users while leaving other time-consuming tasks such as provisioning, automatic scaling, maintaining infrastructure and patching the provider to handle it for you, Netlify and FaunaDB in this case.

NOTE:
It’s possible to hit FaunaDB GraphQL endpoints from the browser over HTTP, but in this case, we will make use of Netlify Functions for our server-side logic. Hence, our use of Netlify Functions.

Application Flow.

Our basic flow for shortening a link will be as follows.

Enter your long URL in a form. In this case an HTML form from our React frontend.
Check for URL validity by using Regex pattern to test if the input is a valid URL.
This input is then sent to your database and a short URL is generated. All this will be taken care of using the Netlify Function. If successful, the short URL will be sent back to the client as the short version of their URL.
On the part of resolving shortened links, once a URL is visited, all requests meant to resolve links will be routed to functions running on Netlify. We will do this by applying routing rules in our netlify.toml file.

Login to your FaunaDB account.

If you don’t have an account, you will be required to sign up to get started which is very easy.

FaunaDB also offers a generous free tier for you not only to test your app but you can also use this to build your small hobby apps.

Creating the GraphQL database.

In order to hold all our application’s data, we will need to create a database.
Click [ New Database], provide any preferred name for the database, in our case, we will name it url_shortener.

Importing your GraphQL schema to FaunaDB.

The beauty of using GraphQL on Fauna is that it allows you to define a schema and it will do its magic to ensure your entities, their relationships are created. All you need to provide is a schema.

On the GraphQL tab, you should see the following page.

Click [Import Schema], and select your schema file and allow for Fauna to do all the magic for you.
Our entire application will be based around this simple schema.

[schema.gql]

type URL {
  short_url: String!
  long_url: String!
}
type Query {
  findURLbyShortURL(short_url: String!): URL
}

Testing queries and mutations.

For our URL shortener to work, we will need to send data to the database to save our long URLs and also need to read the database for stored URLs while resolving these URLs.
In GraphQL lingo, these can be described as mutations and queries respectively.
In order to understand how this works and whether it really works, let's test these using the GraphiQL interface provided by Fauna.

To test saving a link, we can do the following.

[Test Mutation Code Snippet]

 # Write your query or mutation here
mutation {
          createURL(data:{
            short_url:"fdb", 
            long_url:"https://fauna.com"
          }) {
            short_url
            long_url
            _id
          }
}

[Test Mutation Screenshot]

Now, we can test retrieving the link we just saved, we can use the following code.

[Testing Querying Code Snippet]

# Write your query or mutation here
query {
        findURLbyShortURL(short_url:"fdb"){
      long_url
        _id
        _ts
  }
}

[Testing Querying Screenshot]

TIP:
You may notice two ‘strange’ fields (_ts and _id) while querying your saved data.
Fauna automatically takes care of creating two fields for you. A unique identifier (_id) and the timestamp (_ts). Therefore you don’t really have to worry about creating these yourself. Simply saving your data will ensure the two fields are automatically present which I really like.

Obtain your API key and save it.

On the security tab, select [New Key]

Then proceed to select the type of key you want to create. In this case, a Server Key is sufficient to provide access to our database.

NOTE:
Fauna allows you to create two types of keys.

Admin: Used to create, destroy, or manage any database or key.
Server: Can be used to create, destroy, or manage the database to which they are assigned.

In order to access this database from any external application, FaunaDB requires you to provide this key for it to determine which database you have permission to access.
Save it somewhere safely as you will require it in the upcoming steps.
You can now make it available in your env by using the following command.

export FAUNA_SECRET=yourfaunaAPIkey

Structuring the project

Creating the React App.

We will download and run the official Netlify create-react-app and Lambda starter kit. This will set us up with a base for both our frontend and backend code and allow us to quickly get started.

We will run the following commands

git clone https://github.com/netlify/create-react-app-lambda.git
cd create-react-app-lambda
npm install

Let’s take a quick look at the file structure here:

package.json: This application's dependencies, shared between client and server code.
netlify.toml: The configuration that Netlify will use for our application.
src/: The source code for the React frontend app.
src/lambda/: The server source code that will be deployed to Netlify Functions.

Add your functions in the lambda folder.

Inside your app directory, you will find a lambda folder.
The functions in our application are going to live in this lambda folder. You can set up this to be whatever you want but Netlify recommends using this convention.
In the case of this tutorial, we will only have two functions.

Shorten URL - Take the long URL, save it on Fauna and return a short URL.
Resolve URL – Takes a short URL and will return the original long URL.

Write code for the two functions.

Since we will use Apollo to access our GraphQL API, install it then create a ‘utils.js’ file to maintain a cleaner code and allow for code reuse instead of initializing it twice.

[utils.js]

import { ApolloClient, InMemoryCache } from '@apollo/client';
import fetch from 'isomorphic-fetch';

const URL = 'https://graphql.fauna.com/graphql'

const client = new ApolloClient({
   uri: URL,
   fetch: fetch,
   headers: {
       authorization: “Bearer ${process.env.FAUNA_SECRET}“,
   },
   cache: new InMemoryCache({}),
 })

export default client;

Inside the functions directory we created above, we will write two functions.
We will create two files shortenURL.js and resolveURL.js
Inside src/lambda/shortenURL.js write the following code.

[shortenURL.js]

import { gql } from '@apollo/client';
import client from './utils';


export async function handler(event, context) {

   if (event.httpMethod === 'POST'){
       // get data from POST request
       console.log(event)
       let long_url = JSON.parse(event.body).long_url;

       let SHORTEN_URL_QUERY = gql`
           mutation {
             createURL( data:{short_url: "${(Math.random().toString(36).substring(7))}", long_url:"${long_url}"})
                       {
                           short_url
                           long_url
                       }
           }`;
        let results = await client.mutate({
           mutation: SHORTEN_URL_QUERY
       })

       console.log(results.data.createURL.short_url);
       return {
           statusCode: 200,
           body: JSON.stringify({

"short_url":results.data.createURL.short_url }),
       }
   }
   else {
       return {
           statusCode: 405,
           body: JSON.stringify({ error: "Method not allowed" })
       }
   }

}

Inside src/lambda/resolveURL.js write the following code.
[resolveURL.js]

import { gql } from '@apollo/client';
import client from './utils';

export async function handler(event, context) {

   let short_url = event.path.split('/', 5)[4];
   let RESOLVE_URL_QUERY = gql`
     query {
           findURLbyShortURL(short_url:"${short_url}"){
           long_url
       }
     }
   `;
   let results = await client.query({
       query: RESOLVE_URL_QUERY
     })

   return {
     statusCode: 301,
     // send HTTP redirect headers (Location)
     headers:{
       Location: results.data.findURLbyShortURL.long_url
     },
     body: results.long_url,
   }
}

TIP:
Once you are done. It is always good development practice to test these functions. Netlify provides a CLI tool to quickly test your functions locally. You can install it by running.
npm install netlify-cli -g

Then on your command line use
ntl dev

Implement React Frontend

Now that we have our functions working, we will need to connect them to our frontend.

We will create a simple input form with a button to allow the user to enter a long URL and send it over to a function that will take care of generating a short URL and the save it to FaunaDB.
To do this, go to your src/app.js file and add the following code.

[*app.js]

import React, { useState } from "react";
const node_fetch = require('node-fetch');

export default function App(props) {
 const [URL, setURL] = useState("");

 const shortenURL = async function(long_url) {

   let response = await node_fetch('/.netlify/functions/shortenURL', {
     body: JSON.stringify({long_url: long_url}),
     method: 'POST',
     mode: 'no-cors'
   })
   let data = await response.json();
   return data;
 }
  const handleSubmit = async (event) => {
   event.preventDefault();
     if (URL !== ""){
       event.preventDefault();
       await shortenURL(URL).then(data => {
         alert(“http://”+window.location.hostname + “/”+ data.shorturl);
       })
     }
     else{
       alert(`Provide a valid URL`)
     }
 }
 return (

   <form style={{margin:"auto", textAlign:"center"}}>
     <h5>Fauna URL Shortener</h5>
     <label>
       URL to shorten:
       <input type="text" value={URL} onChange={e => setURL(e.target.value)} />
     </label>
     <input type="button" value="Shorten" onClick={handleSubmit} />
   </form>
 );
}

This will have your application looking like in the below figure.

Linking functions to React Application.

We need a way to tell our React code to call the functions as required to ensure the application flow works as desired.

For URL resolution requests, we don’t need to load our React application in order to perform the redirect.
Instead, in the netlify.toml file at the root of our project, we will add the following line.

[[redirects]]
  from = "/*"
  to = "/.netlify/functions/resolveURL/:splat"

Now all requests beyond the / route will be redirected to our resolver function to take care of the routing to that URL.

Deployment.

Other possibilities.

You can allow users to shorten their URL and provide customized short links that could stand for events, entities or literally anything.
You can enable analytics for URL shortened
You can switch from using GraphQL and use FQL instead.