LAB3_Expose your "hello world" API
The REST API is stateless, and therefore helps functions scale horizontally. Here we will:
- Create test cases to check that our API call is working correctly
- Build the API call to Astra to create a game document, based on the requirements from our test
- Setup your environment
- Make a serverless endpoint using Netlify functions
- Merge back to master
- Check your deployment in Netlify
- Summary
IMPORTANT! Don't forget to save when making code changes in your IDE or you might not get expected results.
To code during the workshop you can either use your laptop or the Cloud-based IDE Gitpod with everything installed.
GitPod online IDE (recommended)
Here we explain the Gitpod way
Gitpod is a cloud based IDE based on Eclipse Theia very similar to VSCode. You need to authenticate with your Github account and GitPod will initialize your workspace, building the solution. To initialize your environment follow the instructions below.
✔ Open a new tab in your browser and paste in the following partial URL. Do not submit the page just yet.
gitpod.io/#
✔ Now, go to YOUR battlestax repository and copy its URL.
✔ Finally, paste your repo URL at the end of the gitpod URL combining the two and hit
enterto submit the page.
Once started your page should look something like this.
Notice the blue cube. You may also see some messages about downloading images. It might take a minute for the environment to startup, but if you are seeing this you should be good to go. Move on to the next step.
Local IDE
Here we explain how to work locally
+ We assume people working locally are not beginners + They should be autonomous to install a development > environment.Here are the tools you need:
- NodeJS 12.x+
- Git
- An IDE like Visual Studio Code or Jetbrain WebStorm or Atom
✔ Clone your
BattleStaxrepository to localhost, use the following command in your terminal to do so:git clone git@github.com:[your_github_id]/battlestax.git✔ Move to the proper directory
cd battlestax✔ Install Battlestax Dependencies. These are specified in the
package.jsonfile.npm install
First things first. Let's ensure you are working out of the correct repository using git remote -v.
Ensure you are in the battlestax directory before running the following commands.
git remote -vRunning this command will display the GitHub repository you are working out of.
If it is, please kill the GitPod instance you are working out of and start GitPod from the repository you created earlier using the DataStax-Examples template. This will ensure you are on a happy path to pushing your changes to your production site.
We just need to configure the default remote once. Run the below command to set your configuration.
git config checkout.defaultRemote originCreate a local branch named myBranch
We'll create a feature branch to record changes locally and then push to master when we're ready to deploy.
git checkout -b myBranchEach file in our functions folder represents a REST API endpoint implemented as a serverless function (we'll get to this in a moment). For now, take a look at the helloWorld.js file inside the functions folder.
At this point, this REST API endpoint is stubbed out. You'll need to fill it out with the code below. If we use this as it, it will simply give us back {"hello":"world"}.
exports.handler = async (event, context) => {
return {
statusCode: 200,
body: JSON.stringify({ hello: "world" }),
};
};Now that our code is ready it's time to run the application and access our "helloWorld" endpoint.
NOTE: BattleStax uses both ports 3000 and 8888. If you are running this locally on your machine, you might want to kill anything using the ports before starting the application. GitPod users should not have any conflicts.
npm run devThis will launch the UI and run the helloWorld function in the background.
GitPod users, you might notice a frowny face image like below. Don't worry! This is not an issue and we'll be previewing our helloWorld function here in just a moment.
GitPod online IDE
Here we explain the Gitpod way
Since we started the application in the foreground, we'll need to open another terminal window in GitPod to execute the next command. To do so, navigate to
Terminalin the toolbar and chooseNew Terminalfrom the dropdown.
Using your new terminal, execute the following command to generate your GitPod endpoint and preview the helloWorld serverless function in GitPod's preview window.
gp preview "$(gp url 8888)/.netlify/functions/helloWorld"
{"hello":"world"}This is our serverless function giving us back the "Hello World" example.
Notice the port, GitPod generated ID, and the GitPod region in the URL below at each arrow. This should automatically be generated for you when you run
npm run dev. Just add/.netlify/functions/helloWorldon to the end in order to get to the correct endpoint. We've already done this for you above, but it's good to understand where the endpoint URL is coming from.
Local IDE
Here we explain how to work locally
localhost:8888/.netlify/functions/helloWorld
{"hello":"world"}This is our serverless function giving us back the "Hello World" example.
✔️ Have a look at the /test/helloWorld.test.js file. This tests the helloWorld function to ensure that we get "world" in our response, and hence we would know that the function is working correctly.
Run the test to try it out: NOTE: Local users may need to open another terminal to run the following test.
$(npm bin)/jest test/helloWorld.test.js --coverage --setupFiles dotenv/config --testEnvironment node
Now that we've updated our code we need to push these changes back to master and kick off an automated deploy in Netlify. We'll do this by committing our changes locally, pushing them up to our repository, then creating a pull request to merge them back to master.
Ensure you are executing commands from the battlestax directory.
git add functions/helloWorld.js test/helloWorld.test.jsgit commit -m "Merging helloWorld into master"git push --set-upstream origin myBranchOnce you've pushed your changes go back to your repository in GitHub create a pull request to merge your myBranch changes into master. Ensure that you are merging back into your YOUR master branch.
Using Github UI, merge your new branch to the master using a pull request.
✔️ Select the myBranch branch in github, then click the Pull request button on the right
✔️ Verify base displays base: master and compare displays compare: myBranch
✔️ Provide a comment and click Create Pull Request
✔️ Once your tests have passed, click on Merge Pull Request.
This is going to take a couple minutes as the merge process will install and run application tests automatically using GitHub actions.
✔️ Click on Confirm Merge
Congratulations you are done, it should look something like this
At this point you should see that your pull request kicked off a Deploy Preview in Netlify. Once all tests have passed you can confirm your merge.
✔️ Browsing Netlify, navigate to Deploys, and see the CI/CD process rolling with our deployments
Feel free to click on any items in the deploy list to see logs and other useful information about your deployments.
Once completed Netlify will automatically push the confirmed changes into production. No need to manually deploy anything separately, just push into your repo and production happens.
Finally, you can check that your new helloWorld function is deployed and accessible from production.
Now that we've successfully deployed your helloWorld serverless function simply by merging back to master in GitHub, we should check that it's actually there and working.
✔️ In Netlify, navigate to Functions in the toolbar, then click the helloWorld function in the list.
You may need to use your browser back button if you checked out some logs from the previous step.
✔️ Copy the function endpoint from the browser window and paste into a new tab.
Ok, that was arguably a lot of stuff, but we wanted to break down the process at least once. It might feel like a lot of steps on the first couple runs, but as you get used to it the flow becomes quite natural.
- make changes to your branch
- push those changes back to GitHub
- use a pull request to merge the changes back to master
- CI/CD automatically checks your application using GitHub actions and the Netlify integration
- confirm merge
- changes are automatically pushed to production
In the future, we won't break it down quite so much, but feel free to use this section as a reference as we move forward.
Before moving on, take a moment to let this sink in. You just deployed an app with a serverless function to production over a globally supported CDN using a full CI/CD pipeline all by merging your code into master. Boom!
