How to structure serverless Function in Gatsby

The serverless function is builtin into Gatsby's framework. To create a serverless function, we can create a file ending with .js extension at the below location:

• /src/api/

The file available in the above folder serves as the API route in Gatsby. For example, we can create a file at the below location

• /src/api/status.js

In the status.js file, we can paste the code below.

export default function handler(
  req,
  res
) {
  res.status(200).send({
    msg: `hello world`
  })
}

To test the response of the above serverless function, we can use the following tools as below:

• Browser
• Postman Tool

(Option 1) We can use your local system browser to test the response of the serverless function. For the status.js serverless function, Gatsby creates the API route in the browser at the below location:

• http://localhost:8000/api/status

In the below image, we can view the response of the above API route...

(Option 2) To test the API route in the Postman, we first need to download the tool at the below location:

• https://www.postman.com

In the postman tool, you can test the response of the API route as below:

In the above, we send a GET HTTP request to the API route to fetch the response.

From the browser, we can only send the GET request. If a serverless function needs some additional parameter to execute successfully, we need to send a POST request. The POST method is used to send the payload data along with the request.

Payload along with the HTTP request

In the function, we need to pass the additional payload (parameters).

For example, for authorization (login) we need to send the email and password data as a payload.

To pass the payload, we can rewrite the status.js serverless function code as below.

export default function handler(req, res) {
  res.status(200).send({
    msg: `hello ${req.body.name}`,
  })
}

The above function requires one (1) payload data as below:

1. name

If we now hit the API route, the below response is received as a result

Please note that the name is undefined in the API response.

Again, we can update the below line of code in the status.js file as below.

We can pass the payload in the query of the URL as below.

Please note that the URL length limit is 2048 characters. If the queries in the website exceed the limit length, payload will not pass to the function.

Alternatively, we can send the POST request. In the POST request, we can send the payload in the body of the HTTP request. We can send the POST request in the request body using Postman as below

Error handling in Serverless function

In the serverless function, we may encounter the error due to several reasons e.g. syntax error, missing payload information, etc.

We can send the error response in the serverless function if the payload data is missing. For that, we can rewrite the status.js function as below.

export default function handler(req, res) {
  try {
    const name = req?.body?.name || req?.query?.name
    if (!name) {
      throw {
        status: 500,
        message: "Name field is required.",
      }
    }

    res.status(200).send({
      msg: `hello ${name}`
    })
  } catch (error) {
    const status = error.response?.status || error.statusCode || 500
    const message = error.response?.data?.message || error.message

    res.status(status).json({
      message: error.expose ? message : `Faulty ${req.baseUrl}: ${message}`,
    })
  }
}

In the above serverless function, we use try {} catch (e) {} statement to handle the error. If the name payload is missing, we can throw an error as a response as below.