HTTP routes 

What is an HTTP route in Gadget? 

An HTTP route is a server-side function that runs when a URL is visited to produce a response. Gadget matches incoming requests to routes based on each route's URL pattern, and then runs the handler function and sends the reply. Routes in Gadget are constructed using Fastify routes, which means your handlers can use all of Fastify's capabilities including body parsing, validation, middleware support, and the Fastify plugin ecosystem.

When do you use an HTTP route in Gadget? 

HTTP routes are used as an alternative solution to Actions when you need to specifically control the request input and output formats. Usually, Actions are the preferred way of working with your app, as you get an auto-generated, typesafe, performant API for each Action out of the box. HTTP routes work better when you need low-level control, like:

• handling webhooks from connections not provided by Gadget (Ex. Stripe or Twilio)
• dynamically generating files (Ex. PDFs or images)
• serving static files

For example, if you wanted to send an SMS every time a Shopify Product is created in a store, you would use a model action because Gadget has a connection that handles triggers for Shopify's webhooks. But, if you wanted to send an SMS when Stripe sends you a specific webhook, you'd listen to that webhook with an HTTP route and trigger your logic there.

How an HTTP route works in Gadget 

HTTP routes in Gadget are defined as files in the routes folder. Each route has a specific filename which determines the URL path the route will be called at, like GET-hello.js or /[slug]/POST-[id].js. The route will be called whenever a request is made to a URL matching the pattern in the filename.

Route files export a single function accepting a request context object. The request context includes:

• a request object for inspecting the incoming request headers, body, etc
• a reply object for managing the response
• a variety of other objects for working with your backend

How to add an HTTP route to Shopify apps in Gadget 

Unlike the default web app template, when building a Shopify app (by choosing the Shopify template) it does not come with HTTP routes and its corresponding folder.

To create an HTTP route in a Shopify app:

1. Press CRTL and click on the API folder and select New folder.

2. Name the folder routes.
3. Add a new JS file to the routes folder (for example we'll add GET-data.js as seen below).

4. In the newly created file you then should see the default code below:

1import { RouteHandler } from "gadget-server";
2
3/**
4 * Route handler for GET data
5 *
6 * See: https://docs.gadget.dev/guides/http-routes/route-configuration#route-context
7 */
8const route: RouteHandler = async ({
9  request,
10  reply,
11  api,
12  logger,
13  connections,
14}) => {};
15
16export default route;

1import { RouteHandler } from "gadget-server";
2
3/**
4 * Route handler for GET data
5 *
6 * See: https://docs.gadget.dev/guides/http-routes/route-configuration#route-context
7 */
8const route: RouteHandler = async ({
9  request,
10  reply,
11  api,
12  logger,
13  connections,
14}) => {};
15
16export default route;

And you've now successfully created your first HTTP route in Gadget.