DEV Community

Cover image for Beginner's Guide for Creating a Serverless REST API using NodeJS over Google Cloud Functions
Levi Velázquez
Levi Velázquez

Posted on • Edited on

Beginner's Guide for Creating a Serverless REST API using NodeJS over Google Cloud Functions

#webdev #beginners #javascript #serverless

API REST using Google Cloud Functions (Serverless)

Serverless application has gained a lot of importance over time. It allows focussing on your app code/tests without worrying about configurations, deployment process or scalability.

We're going to create a function that will be exposed via rest URL. That function will be invoked every time a HTTP(S) request is received.

During execution, an express server will be summoned exposing our REST services.

What we are going to build?

  • Express API for CRUD services(create, read, update and delete) on a Firestore database.
  • Use Google Cloud Function to expose our Express server
  • Deploy our Google Cloud Function using Cloud CLI.

 Creating our firebase project

In order to create our first project, let's do it here. Select add project, project's name must be unique, let's use prefix github-ring-{github_user}, github-ring-levinm in my case. Be sure to select Firestore as our database.

image1

For creating our database, click on Develop>Database and select "start in test mode".

image2

Initializing our project locally

We need to install firebase using NPM.



npm install -g firebase-tools
Enter fullscreen mode Exit fullscreen mode

Then, let's login into our firebase account.



firebase login
........... input credentials
Enter fullscreen mode Exit fullscreen mode

Initialize the project



firebase init
........ select project
Enter fullscreen mode Exit fullscreen mode

image3

It will prompt an interactive console.

  1. Select Functions and Hosting options.
  2. What language would you like to use to write Cloud Functions? TypeScript
  3. Do you want to use TSLint to catch probable bugs and enforce style? Yes
  4. Do you want to install dependencies with npm now? Yes
  5. What do you want to use as your public directory? Press enter to select public (it is the default option)
  6. Configure as a single-page app (rewrite all urls to /index.html)? No

We're ready, our firebase project was initialized.

Installing Express.js and dependencies 



cd functions
npm install --save express body-parser
Enter fullscreen mode Exit fullscreen mode

Creating our Google Cloud Function

Open src/index.ts, it will be the entrypoint for our Express.js server

 Import main libraries 



import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
import * as express from 'express';
import * as bodyParser from "body-parser";
Enter fullscreen mode Exit fullscreen mode

Initialize firebase for accesing to its services 



admin.initializeApp(functions.config().firebase);
Enter fullscreen mode Exit fullscreen mode

Intialize Express.js server 



const app = express();
const main = express();
Enter fullscreen mode Exit fullscreen mode

Configure the server.

  • Let's add the path used for receiving the request.
  • Select JSON as our main parser for processing requests body.


main.use('/api/v1', app);
main.use(bodyParser.json());
Enter fullscreen mode Exit fullscreen mode

 Export our function.

Last but not least, let's define our Google Cloud Function name, we are going to expose it using export. Our function will receive an express server object(this case main) which will be used for request processing. If you want more information regarding how it works, you can check this good answer on Stackoverflow



export const webApi = functions.https.onRequest(main);
Enter fullscreen mode Exit fullscreen mode

Creating our first service

Let's expose a GET endpoint returning just a string. 



app.get('/warm', (req, res) => {
    res.send('Calentando para la pelea');
})
Enter fullscreen mode Exit fullscreen mode

Our src/index.ts file should look like this:




import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
import * as express from 'express';
import * as bodyParser from "body-parser";

admin.initializeApp(functions.config().firebase);

const app = express();
const main = express();

main.use('/api/v1', app);
main.use(bodyParser.json());

export const webApi = functions.https.onRequest(main);

app.get('/warmup', (request, response) => {

    response.send('Warming up friend.');

})
Enter fullscreen mode Exit fullscreen mode

 Deploying our function.

Before deploying it, we need to change our config file firebase.json as follows:

{
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  },
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "/api/v1/**",
        "function": "webApi"
      }
    ]
  }
}

This rule allows "to route" all requests sent through api/v1 to be served by webApi function (Our exported one).

Also, Google CLI installs Typescript v2 by default. So, we need to update our typescript version >=3.3.1. You can do it in functions.package.json. 

  "devDependencies": {
    "tslint": "~5.8.0",
    "typescript": "~3.3.1"
  },

Re-install dependencies.



cd functions
npm install
Enter fullscreen mode Exit fullscreen mode

We are ready for deploying.



firebase deploy
Enter fullscreen mode Exit fullscreen mode 


.....
✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/github-ring-levivm/overview
Hosting URL: https://github-ring-levivm.firebaseapp.com
Enter fullscreen mode Exit fullscreen mode

If everything is ok, Hosting URL will be our Google Cloud Function endpoint.

 Testing our function

Let's send a GET request using CURL



$ curl -G "https://github-ring-levivm.firebaseapp.com/api/v1/warmup"
Warming up friend.
Enter fullscreen mode Exit fullscreen mode

Rest API CRUD

Let's add our CRUD endpoints. We are going to manage fights information.

Create a record

First, let's initialize our database. We open our src/index.ts and add this after admin initialization




admin.initializeApp(functions.config().firebase);
const db = admin.firestore(); // Add this
Enter fullscreen mode Exit fullscreen mode

In order to create a fight record, let's create POST /fights/ endpoint. Our fight record is going to have a winner, loser and title.



app.post('/fights', async (request, response) => {
  try {
    const { winner, loser, title } = request.body;
    const data = {
      winner,
      loser,
      title
    } 
    const fightRef = await db.collection('fights').add(data);
    const fight = await fightRef.get();

    response.json({
      id: fightRef.id,
      data: fight.data()
    });

  } catch(error){

    response.status(500).send(error);

  }
});
Enter fullscreen mode Exit fullscreen mode
  • We get our post data using request.body
  • We use add() method to add a new fight, if the collection doesn't exist (our case), it will create it automatically.
  • In order to get the actual record data, we must use get() over the ref.
  • Return a json using response.json.

 Get a record

We create a GET /fights/:id endpoint in order to fetch a fight by id.



app.get('/fights/:id', async (request, response) => {
  try {
    const fightId = request.params.id;

    if (!fightId) throw new Error('Fight ID is required');

    const fight = await db.collection('fights').doc(fightId).get();

    if (!fight.exists){
        throw new Error('Fight doesnt exist.')
    }

    response.json({
      id: fight.id,
      data: fight.data()
    });

  } catch(error){

    response.status(500).send(error);

  }

});
Enter fullscreen mode Exit fullscreen mode
  • We get the fight id using request.params.
  • We validate if the id is not blank.
  • We get the fight and check if it exists.
  • If fight doesn't exist we throw an error
  • If fight exists, we return the data.

 Get a record list

We create a GET /fights/ endpoint.



app.get('/fights', async (request, response) => {
  try {

    const fightQuerySnapshot = await db.collection('fights').get();
    const fights = [];
    fightQuerySnapshot.forEach(
        (doc) => {
            fights.push({
                id: doc.id,
                data: doc.data()
            });
        }
    );

    response.json(fights);

  } catch(error){

    response.status(500).send(error);

  }

});
Enter fullscreen mode Exit fullscreen mode
  • We get a collection snapshot.
  • We iterate over every document and push the data into an array.
  • We return our fight list.

 Update a record

We must create a PUT /fights/:id endpoint in order to update a fight by id.



app.put('/fights/:id', async (request, response) => {
  try {

    const fightId = request.params.id;
    const title = request.body.title;

    if (!fightId) throw new Error('id is blank');

    if (!title) throw new Error('Title is required');

    const data = { 
        title
    };
    const fightRef = await db.collection('fights')
        .doc(fightId)
        .set(data, { merge: true });

    response.json({
        id: fightId,
        data
    })


  } catch(error){

    response.status(500).send(error);

  }

});
Enter fullscreen mode Exit fullscreen mode
  • We get request data.
  • We validate the data
  • We update a record using set(data, merge: true). It means it is going to update only the fields passed on data parameter.

 Deleting a record.

For deleting a fight, we need to add an endpoint DELETE /fights/:id. 




app.delete('/fights/:id', async (request, response) => {
  try {

    const fightId = request.params.id;

    if (!fightId) throw new Error('id is blank');

    await db.collection('fights')
        .doc(fightId)
        .delete();

    response.json({
        id: fightId,
    })


  } catch(error){

    response.status(500).send(error);

  }

});
Enter fullscreen mode Exit fullscreen mode
  • We get the fight id.
  • We use delete() in order to delete a doc instance (Remember that firestore is database based on documents( "NoSQL" ))

Our src/index.ts file should looks like this



import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
import * as express from 'express';
import * as bodyParser from "body-parser";

admin.initializeApp(functions.config().firebase);
const db = admin.firestore(); // Add this

const app = express();
const main = express();

main.use('/api/v1', app);
main.use(bodyParser.json());

export const webApi = functions.https.onRequest(main);

app.get('/warmup', (request, response) => {

    response.send('Warming up friend.');

});

app.post('/fights', async (request, response) => {
  try {
    const { winner, losser, title } = request.body;
    const data = {
      winner,
      losser,
      title
    } 
    const fightRef = await db.collection('fights').add(data);
    const fight = await fightRef.get();

    response.json({
      id: fightRef.id,
      data: fight.data()
    });

  } catch(error){

    response.status(500).send(error);

  }
});

app.get('/fights/:id', async (request, response) => {
  try {
    const fightId = request.params.id;

    if (!fightId) throw new Error('Fight ID is required');

    const fight = await db.collection('fights').doc(fightId).get();

    if (!fight.exists){
        throw new Error('Fight doesnt exist.')
    }

    response.json({
      id: fight.id,
      data: fight.data()
    });

  } catch(error){

    response.status(500).send(error);

  }
});

app.get('/fights', async (request, response) => {
  try {

    const fightQuerySnapshot = await db.collection('fights').get();
    const fights = [];
    fightQuerySnapshot.forEach(
        (doc) => {
            fights.push({
                id: doc.id,
                data: doc.data()
            });
        }
    );

    response.json(fights);

  } catch(error){

    response.status(500).send(error);

  }

});

app.put('/fights/:id', async (request, response) => {
  try {

    const fightId = request.params.id;
    const title = request.body.title;

    if (!fightId) throw new Error('id is blank');

    if (!title) throw new Error('Title is required');

    const data = { 
        title
    };
    const fightRef = await db.collection('fights')
        .doc(fightId)
        .set(data, { merge: true });

    response.json({
        id: fightId,
        data
    })


  } catch(error){

    response.status(500).send(error);

  }

});

app.delete('/fights/:id', async (request, response) => {
  try {

    const fightId = request.params.id;

    if (!fightId) throw new Error('id is blank');

    await db.collection('fights')
        .doc(fightId)
        .delete();

    response.json({
        id: fightId,
    })


  } catch(error){

    response.status(500).send(error);

  }

});
Enter fullscreen mode Exit fullscreen mode

 Testing

We deploy our function.



firebase deploy
....
Enter fullscreen mode Exit fullscreen mode

We test all our endpoints.



# Testing create fight (POST /fights)
$ curl -d '{"winner":"levi", "losser":"henry", "title": "fight1"}' -H "Content-Type: application/json" -X POST "https://github-ring-levivm.firebaseapp.com/api/v1/fights/"

> {"id":"zC9QORei07hklkKUB1Gl","data":{"title":"fight1","winner":"levi","losser":"henry"}

# Testing  get a fight (GET /fight:id)
$ curl -G "https://github-ring-levivm.firebaseapp.com/api/v1/fights/zC9QORei07hklkKUB1wGl/"

>{"id":"zC9QORei07hklkKUB1Gl","data":{"winner":"levi","losser":"henry","title":"fight1"}}


# Testing get fights list (GET /fights/)
$ curl -G "https://github-ring-levivm.firebaseapp.com/api/v1/fights/"
> [{"id":"zC9QORei07hklkKUB1Gl","data":{"title":"fight1","winner":"levi","losser":"henry"}}]

# Testing update a fight (PUT /fights/:id)
$ curl -d '{"title": "new fight title"}' -H "Content-Type: application/json" -X PUT "https://github-ring-levivm.firebaseapp.com/api/v1/fights/zC9QORei07hklkKUB1Gl/"

> {"id":"zC9QORei07hklkKUB1Gl","data":{"title":"new fight title"}}

# Testing delete a fight (DELETE /fight/:id)
$ curl -X DELETE "https://github-ring-levivm.firebaseapp.com/api/v1/fights/zC9QORei07hklkKUB1Gl/"

> {"id":"zC9QORei07hklkKUB1Gl"}
Enter fullscreen mode Exit fullscreen mode

And we are done, we have built our API Rest using Google Cloud Function (Serverless).

Note: You can check your database using Firestore interface within our Firebase console.

image4

If this was helpful, share it :).

If you like my content or it was helpful, you can motivate me to write more content by buying me a coffee

Top comments (44)

Collapse
 
lcarbonaro profile image
Les Carbonaro •

Thank you Levi for this tutorial. It was very clear and easy to follow for the most part. I had an error come up from firebase deploy regarding firebase-function-helper but I see that you have since removed that import line.

In my case, I did not use Typescript or TSLint, so I had to remove the predeploy steps in firebase.json. Also the imports in index.js had to be require in my case.

The only thing I added was cors, so as to be able to call the endpoints from a front-end on a different domain, like now or Netlify, for example.

Also, other (older) tutorials I followed had mentioned downloading service account settings as a json file and then importing that in the project. A bit of a hassle. Your solution is much cleaner in this regard and, as a result, more portable.

Thank you again for a very helpful article.

Collapse
 
levivm profile image
Levi Velázquez •

I'm glad it was useful to you.

Yep, I need to add cors so you can use the endpoints from another domain.

Thanks for the feedback.

Collapse
 
psidneyrobinson profile image
Sid Robinson • • Edited

Hey there, I'm having a hard time getting this deployed. I've copied your index.ts file so I know the file is good, I just can't figure out why my code is breaking. I'm attaching a screenshot but not sure it's coming threw.

Collapse
 
levivm profile image
Levi Velázquez •

I can't see the screenshot.

Collapse
 
psidneyrobinson profile image
Sid Robinson •

Yeah.. not sure why it didn't work.. here is an url.. sidneyphillip.com/screenshot.png

Thread Thread
 
levivm profile image
Levi Velázquez •

This is about your TS lint configuration, it isn't nothing about the platform itself.

Check this answer: stackoverflow.com/questions/430642...

Let me know if you need anything else.

Collapse
 
khmaies5 profile image
Khmaies Hassen •

I have a dumb question :p
Why we have to build an api for firebase database and not directly use the firebase api to access our firestore database?

Collapse
 
levivm profile image
Levi Velázquez • • Edited

This is a simple tutorial, I tried to keep our endpoints simpler as possible but most cases you need to have authentication, you need to do extra processes before inserting a record, you need to create an extra task, handle permissions, roles, etc. This is a backend service, it isn’t about just accessing database.

If you have any other question, feel free to ask :)

Collapse
 
dizid profile image
Marc de Ruyter •

i have a url-shortener without users logging in. I cannot write to firestore from the Vue client because the firestore rules need a user logged in. I can also not use the firebase-admin because the code runs on the client. So, now i am trying a cloud function as an API relay.

Collapse
 
levivm profile image
Levi Velázquez •

But you can authenticate using an anonymous login(it is available on firebase), so, you can login user using token generates from the client without having username or password.

Thread Thread
 
dizid profile image
Marc de Ruyter •

HI Levi, Thanks for the tip, i will look into that!

Collapse
 
spock123 profile image
Lars Rye Jeppesen •

Functions as a backend only works for the US region.

In other words, it's a no-go for people using firebase hosting, database, storage in other regions, as latency will be atrocious.

We had our entire backend rewritten as functions before we discovered this issue. Had to completely abandon Firebase functions because all our other Firebase assets are located in Europe. So we moved our backend elsewhere, unfortunately.

Just be aware guys: functions as an API for your frontend ONLY works for US region. We had 500ms latency for every request because of this.

Collapse
 
johnswicks profile image
johnswicks • • Edited

Hey Man thanks for helping out everyone.I have read data from all documents in a collection but I cannot get into my subcollections of cloud firestore. I am trying to get result from subcollections but I always get []. I would be very helpful if you share piece of code.

Sample Collection:
Users(collection)->Id(Documents in collection)->ratedBy(Sub collection in document)-> detail(ratedby document)

Collapse
 
alextoul profile image
Alexandre Toulemonde • • Edited

Since Jan 2020, we need extra settings to make the API calls public once deployed.

gcloud functions add-iam-policy-binding webApi \
--member="allUsers" \
--role="roles/cloudfunctions.invoker"

Collapse
 
projectcorrelationrelationship profile image
Project-Correlation-Relationship •

Hi, Excellent tutorial. I using Windows 10, and I managed to get almost all the way through but after I run the firebase deploy, I am getting the following error

"debug] [2021-01-26T09:35:46.363Z] Error: EPERM: operation not permitted, scandir 'c:/Users/abc/AppData/Local/Application Data'

Any pointers please.

Collapse
 
hungtranpg profile image
hungtranpg • • Edited

Great tutorial!
Should we have only one large Express app to handle all requests? Or should we divide it to multi-app by functionally?
Because of some limits
cloud.google.com/functions/quotas

Collapse
 
moevans2018 profile image
Mitch Evans •

Will you or have you created a tutorial that follows this for authentication and use of API Keys? I found this article EXTREMELY useful and would love a follow up!

Collapse
 
levivm profile image
Levi Velázquez •

Yep, I'm just writing it, I'm planning to release it next week.

Glad you found it useful.

Collapse
 
heyconor profile image
Conor •

Hi Levi - Did you ever get around to writing this next post on authentication? I'm looking for a tutorial on how to implement authentication via a firebase-hosted RESTful API, e.g.

  • Login
  • CRUD (but only if user is authenticated)

The approach I'm familiar with is using JWTs with Node, but I appreciate this may be different with Firebase Cloud Functions. I'm not sure.

Collapse
 
interpegasus profile image
Arturo •

Hi Levi, Thanks for the tutorial. Currently, the API endpoints work fine after they are deployed.

However, when running the emulator locally, the API endpoints seem not to be recognized.

URL: mylocal_server/v1/warm or mylocal_server/crew-iq/us-central1...
Browser Output: 'Cannot GET /v1/warm'

Do you know what might cause the issue or what would be the local API endpoint?

$ firebase emulators:start --only functions
i emulators: Starting emulators: functions
✔ functions: Using node@10 from host.
✔ functions: Emulator started at 0.0.0.0:8080
i functions: Watching "/home/ubuntu/environment/Crew-IQ/functions" for Cloud Functions...
⚠ functions: The Cloud Firestore emulator is not running, so calls to Firestore will affect production.
✔ functions[webApi]: http function initialized (0.0.0.0:8080/crew-iq/us-central1/w...).
✔ All emulators started, it is now safe to connect.

View full discussion (44 comments)

Read next

anthonymartin profile image

BREAKING: Intel CEO Resigns After Controversy

anthonymartin -

mahiworld profile image

How to Uncheck All Your Twitter (X) Interests in Bulk with Developer Tools (Quick Method)

Mahendra -

kaankaya profile image

Dirty Code: Simple Rules to Avoid It

Kaan Kaya -

bekbrace profile image

Build TUI application with GO (tview)

Bek Brace -