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 CDN (once deployed), without the need for an actual server to deploy code to. 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 a function is implemented in this fashion 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, take a look at the helloWorld.js file inside the functions folder.

Check out the functions folder: battlestax/functions/helloWorld.js

At this point, this REST API endpoint is stubbed out. You'll need to fill it out with the code below. Click on the copy to editor button in the upper right corner of the code below. If we use this as is, it will simply give us back {"hello":"world"}.

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

Next we are going to test the REST API with a browser. Make sure that you are in the battlestax folder:

cd ~/battlestax

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

npm install

You may get a warning about some vunerabilities, but this is not an issue.

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

clear; npm run dev

This will give you the UI and run the helloWorld function in the background. Once you see the Netlify dev server is ready on port, check out the helloworld endpoint:

https://[[HOST_SUBDOMAIN]]-8888-[[KATACODA_HOST]].environments.katacoda.com/.netlify/functions/helloWorld

You should see this output at the endpoint:

{"hello":"world"}

This is our serverless function giving us back the "Hello World" example.

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

echo "Sending a Ctrl-C"

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

Open the /test/helloWorld.test.js file in the editor:

battlestax/test/helloWorld.test.js

This test is quite simple - it executes the helloWorld function to ensure that we get "world" in the response, letting us know that the function is working correctly.

const helloWorld = require("../functions/helloWorld");

it("should return a JSON response", async () => {
  const response = await helloWorld.handler();
  const responseJson = JSON.parse(response.body);
  expect(responseJson.hello).toBe("world");
});

Run the test to try it out:

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

You should expect to see something similar to the following if the test passes:

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

We will also be making use of the Document API to connect to our Astra database. The Stargate API framework allows developers the freedom to access Astra with a variety of APIs. With the Document API, you can save and search schemaless JSON documents in Cassandra. No need to use SQL, CQL, or any database drivers to talk to the data layer. Just code and move on.

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

Since we already have our game document store (Astra), let's start building our basic insertGame serverless function, in the function/insertGame.js file:

battlestax/functions/insertGame.js

Let's take a walk through the code we are going to implement in insertGame.js first. We need to declare gameId and gamePayload variables. We know each game is associated with its own unique game id, and during game play we can anticipate getting a payload from the user.

// let's declare gameId and gamePayload variables
let gameId;
let gamePayload;

From your Netlify function, you get your gameId parameter from the path of the incoming REST call, and parse the event body that is associated with it as the gamePayload. By default, Netlify puts your function at the path /.netlify/functions/insertGame.

// let's set the game id
gameId = event.path.split("insertGame/")[1];
// 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, a HTTP status code of 400 will be returned and you will get an error message:

...
} catch (e) {
  // 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" }),
  };
}

Now that we have dicussed this portion of our insertGame, let's add the code that we have discussed so far to insertGame.js. Click on the copy to editor button in the upper right corner of the code below.

const { createClient } = require("@astrajs/collections");

exports.handler = async (event, context) => {
  // let's return a 400 if we don't recieve a valid game id
  let gameId;
  let gamePayload;
  try {
    // let's set the game id
    gameId = event.path.split("insertGame/")[1];
    // let's parse the incoming payload
    gamePayload = JSON.parse(event.body);
  } catch (e) {
    // 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!

The next thing we need to do is to connect to our Astra database. We are first going to import the JavaScript SDK library (astrajs) to create our Astra Client. We will use environment variables to pass our credentials to the Astra client so that it can connect to the database, and create a document to store information about our game.

Go HERE for more information on the on the JavaScript SDK library.

Let's walk through the additional code we will be adding to insertGame.js. Make sure you have battlestax/functions/insertGame.js open.

First, make note of how we have imported the JS SDK already at the top of the file:

const { createClient } = require("@astrajs/collections");

We create our astraClient using the environment variables we provided earlier:

// let's connect to Astra
const astraClient = await createClient({
  // let's set our Astra connection configuration
  astraDatabaseId: process.env.ASTRA_DB_ID,
  astraDatabaseRegion: process.env.ASTRA_DB_REGION,
  username: process.env.ASTRA_DB_USERNAME,
  password: process.env.ASTRA_DB_PASSWORD,
});

const gamesCollection = astraClient
  .namespace(process.env.ASTRA_DB_KEYSPACE)
  .collection(process.env.GAMES_COLLECTION);

Finally, we are going to take the configuration information in gamesCollection and provision a new game from it. If this works, we get back a HTTP status code of 200. If it fails, we will get back a 500.

  // let's provision a new game
  try {
    // let's create a new game with the gamesCollection
    const res = await gamesCollection.create(gameId, gamePayload);
    // let's return a 200 with the resoponse from astra
    return {
      statusCode: 200,
      body: JSON.stringify(res),
    };
  } catch (e) {
    console.error(e);
    // let's return a 500 on error
    return {
      statusCode: 500,
      body: JSON.stringify(e),
    };
  }
};

Add the rest of the code to as described above to your insertGame async function. Now the function has the ability to connect to our Astra instance and provision a new game. Click on the copy to editor button in the upper right corner of the code below.

const { createClient } = require("@astrajs/collections");

exports.handler = async (event, context) => {
  // let's return a 400 if we don't receive a valid game id
  let gameId;
  let gamePayload;
  try {
    // let's set the game id
    gameId = event.path.split("insertGame/")[1];
    // let's parse the incoming payload
    gamePayload = JSON.parse(event.body);
  } catch (e) {
    // 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" }),
    };
  }

  // let's connect to Astra
  const astraClient = await createClient({
    // let's set our Astra connection configuration
    astraDatabaseId: process.env.ASTRA_DB_ID,
    astraDatabaseRegion: process.env.ASTRA_DB_REGION,
    username: process.env.ASTRA_DB_USERNAME,
    password: process.env.ASTRA_DB_PASSWORD,
  });

  const gamesCollection = astraClient
    .namespace(process.env.ASTRA_DB_KEYSPACE)
    .collection(process.env.GAMES_COLLECTION);

  // let's provision a new game
  try {
    // let's create a new game with the gamesCollection
    const res = await gamesCollection.create(gameId, gamePayload);
    // let's return a 200 with the resoponse from astra
    return {
      statusCode: 200,
      body: JSON.stringify(res),
    };
  } catch (e) {
    console.error(e);
    // let's return a 500 on error
    return {
      statusCode: 500,
      body: JSON.stringify(e),
    };
  }
};

Let's run our application again again:

npm run dev

Check out the insertGame endpoint in the browser:

https://[[HOST_SUBDOMAIN]]-8888-[[KATACODA_HOST]].environments.katacoda.com/.netlify/functions/insertGame

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

<<<<<<< HEAD Once you finish this step, hit Ctrl+C to stop you application from running.

echo "Sending a Ctrl-C"

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

07e9fefaa4b673bf708919a99f9bbef6df1ef023

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 serverlesss function to provision a new game on Astra -- and we need to provide the API with a random game code so this can work. Our endpoint needs to:

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.

battlestax/test/insertGame.test.js

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 with 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

You should see this if the tests pass:

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.

Open Astra UI, show the CQL Console and execute the following command (here battlestax is your keyspace - if you chose another database name, you'll need to adapt the query accordingly).

SELECT key, text_value FROM battlestax.games;

You should have a result that looks like this:

Fantastic Work!