The REST API is stateless, and therefore helps functions scale horizontally. In this step, we are going to make a serverless endpoint using Netlify functions and the Stargate REST API.

What are Netlify functions?

---

Source: Netlify Documentation

Netlify lets you deploy serverless Lambda functions without an AWS account, and with function management handled directly within Netlify. Your serverless functions are version-controlled, built, and deployed along with the rest of your Netlify site, and we will automatically handle service discovery through our built-in API gateway. This eliminates overhead and brings the power of Deploy Previews and rollbacks to your serverless functions.

Why this is cool? What this translates to is an ability to create serverless functions in your application that can be accessed seamlessly in your local environment or via a global Content Delivery Network (CDN) (once deployed), without having to deploy code to actual servers. Just configure the netlify.toml, create the function, and move on.

How does this work in our application? In BattleStax, we configure netlify.toml functions to use the functions folder within our application.

From there, just drop any functions you intend to be serverless into the functions folder and export a handler.


That's it. Once you implement the function, it will be deployed as a serverless function both locally (in our case) and via a global CDN once pushed to Netlify.

---

Each file in our functions folder represents a REST API endpoint implemented as a serverless function. For now, look at the helloWorld.js file inside the functions folder.

You can see that this REST API endpoint is stubbed out. We'll fill it out with the code below. Click on the copy to editor button in the upper right corner of the code below.

exports.handler = async (event, context) => {
  // let's return a JSON response that looks like: { hello: "world" }
  return {
    statusCode: 200,
    body: JSON.stringify({ hello: "world" }),
  };
};

As you can see, this function returns {"hello":"world"}.

Let's test the REST API. Make sure that you are in the battlestax folder:

cd /root/battlestax

Then, install all the denpendencies needed for the app as listed in package.json. (Hang tight, this will take about a minute):

npm install

You may get a warning about some vulnerabilities which you may disregard.

Let's clear the terminal and run the application in development mode:

clear
npm run dev

This npm command will provide an endpoint, and run the helloWorld function in the background. Wait for the Netlify server to initialize.

Now, check out the helloWorld endpoint. We'll run this cURL command in a second terminal.

curl --request GET https://[[HOST_SUBDOMAIN]]-8888-[[KATACODA_HOST]].environments.katacoda.com/.netlify/functions/helloWorld | jq

You should see this output:

{
  "hello": "world"
}

This is the output from our serverless function example.

Once you finish this step, hit Ctrl+C to stop the application.

^C

Great work! Now let's move on to testing our endpoint!

Open this test file:

Inspect this simple test - it executes the helloWorld function, and expects the resulting JSON value with label hello to have a value of world.

Run the test to try it out:

$(npm bin)/jest test/helloWorld.test.js --coverage --setupFiles dotenv/config --testEnvironment node

When the test passes, you will see something similar to the following:

It's that easy to create and run tests.

Great! Let's get into creating a real REST endpoint for our app!

In the previous step, we pushed a simple helloWorld "test" function to get a feel for how testing works. Now, we are going to start working with the "real" code to get our game endpoint working.

Let's start building our basic insertGame serverless function, in the function/insertGame.js file:

We'll walk through the code as we implement it.

As you can see near the top of the file, we declare the gameId and gamePayload variables. Each game has its own unique game ID, and during game play we get a payload from the user. The Netlify function in this file gets the resulting body of the REST API access.

Using the Netlify function, we get the gameId parameter from the path of the incoming REST call, and parse the event body as the gamePayload. By default, Netlify puts your function at the path /.netlify/functions/insertGame.

Click on the copy to editor button in the upper right corner of the code below.

    // let's set the game id
    gameId = event.path.split("insertGame/")[1];

Similarly, we can get the gamePayload.

Click on the copy to editor button in the upper right corner of the code below.

    // let's parse the incoming payload
    gamePayload = JSON.parse(event.body);

Let's not forget about error handling. If we cannot parse the gameId or body from the incoming REST call, the function will return an HTTP status code of 400.

Click on the copy to editor button in the upper right corner of the code below.

      // let's return a 400 if we can't parse the game id or body
    return {
      statusCode: 400,
      body: JSON.stringify({ message: "must provide a valid game ID" }),
    };

Next up, let's connect to Astra DB!

Let's complete the code for the insertGame async function by connecting to the Astra DB database.

At the top of the file, notice how we import the JavaScript SDK so we can create the Astra DB Client. Find more information about the JavaScript SDK library HERE.

We create our astraClient by passing credentials using the environment variables we set earlier:

Click on the copy to editor button in the upper right corner of the code below.

    // let's set our Astra DB connection configuration
    astraDatabaseId: process.env.ASTRA_DB_ID,
    astraDatabaseRegion: process.env.ASTRA_DB_REGION,
    applicationToken: process.env.ASTRA_DB_APPLICATION_TOKEN,

We'll create a new game using the gamesCollection.

Click on the copy to editor button in the upper right corner of the code below.

    // let's create a new game with the gamesCollection
    const res = await gamesCollection.create(gameId, gamePayload);

If there are no problems creating the game, return a status code of 200.

Click on the copy to editor button in the upper right corner of the code below.

  // let's return a 200 with the response from Astra DB
    return {
      statusCode: 200,
      body: JSON.stringify(res),
    };

But, if there is a problem creating the game, return a status code of 500.

Click on the copy to editor button in the upper right corner of the code below.

    // let's return a 500 on error
    return {
      statusCode: 500,
      body: JSON.stringify(e),
    };

Now, the function has the ability to connect to the Astra DB instance and provision a new game.

Let's run our application again.

npm run dev

Wait for the service to initialize. Then, check out the insertGame endpoint.

curl --request GET https://[[HOST_SUBDOMAIN]]-8888-[[KATACODA_HOST]].environments.katacoda.com/.netlify/functions/insertGame | jq

Look for this message to see that the endpoint is working:

{
  "message": "must provide a valid game ID"
}

Have a look at our running React application on port 3000:

https://[[HOST_SUBDOMAIN]]-3000-[[KATACODA_HOST]].environments.katacoda.com

Once you finish this step, hit Ctrl+C to stop the application.

^C

In the next step, we will be testing it our endpoint!

We approach testing by starting with the question "What does our endpoint need to do?" We want our serverless function to provision a new game on Astra DB -- and we need to provide the API with a random game code so this can work.

The test cases in the file test/insertGame.test.js will check that these conditions are supported by the function in functions/insertGame.js.

Notice that insertGame is required as a dependency in our test.js file.

We are going to use faker.js, a JavaScript library for generating mock data. This mock data is useful when building and testing our application. Hence, we require the faker library.

const faker = require("faker");

✔️ TEST 1: Our API should create the game document. We need to test to see if the insertGame function actually does that:

const gameId = faker.helpers.replaceSymbols("????");

it("should create a game document", async () => {
  const response = await insertGame.handler({
    path: "/functions/insertGame/" + gameId,
    body: '{"user":"me"}',
  });
  expect(response.statusCode).toBe(200);
});

We use a simple async function to do this. faker.helpers.replaceSymbols("????") creates a sample gameId for the path, and some user data in the body. As successful test run will return a 200.

✔️ TEST 2 : Our function must not be able to create a game document without a valid gameId

it("shouldn't create a game document without a game id", async () => {
  const response = await insertGame.handler({ path: "insertGame" });
  expect(response.statusCode).toBe(400);
});

We ensure that our function does not create a game, unless it has been provided with a valid gameId.

Now let's run our tests to see if our function works:

npm run test:functions

If the tests pass, you will see something like this:

Great work! Next we will be checking in on our database.

If your insertGame tests ran successfully, you will have a new game record in the database.

We can use cURL to verify the document exists.

curl --request GET \
https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/$ASTRA_DB_KEYSPACE/collections/games?page-size=20 \
--header "x-cassandra-token: $ASTRA_DB_APPLICATION_TOKEN" | jq

Note: If you run the test several times, you will see several documents in the results.

Fantastic Work!