What used to be web servers, web frameworks, routers, and tons of config is now Begin HTTP functions.
When an HTTP request comes in, your HTTP functions are responsible for (synchronously) handling responses. (Longer-running async tasks can be farmed out to Begin event functions.)
Begin HTTP functions are fast, lightweight, stateless, isolated, highly durable, and require no configuration.
Oh, and provisioning new HTTP functions is a cinch!
To provision a new HTTP function, in the root of your project, open your app's Architect project manifest file (usually app.arc
):
@http
pragma@http
get /foo
, or put /bar
npm start
src/http/
(e.g. src/http/get-foo
& src/http/put-bar
)Here's what a basic Architect project manifest looks like with the above two HTTP functions specified:
@app
your-app-name
@http
get /foo
put /bar
After specifying new HTTP functions in your Architect project manifest and pushing your changes to your repo, the following things happen automatically:
staging
(but not production
, of course)That's all there is to it! Now let's take a closer look at the capabilities of HTTP functions, and how they work.
Each HTTP function maps to a logical HTTP route. For example:
get /
is serviced by the HTTP function in your project at src/http/get-index
get /about
is serviced by src/http/get-about
post /form
is serviced by src/http/post-form
All HTTP functions begin with /
, and can include letters, numbers, and slashes, underscores, dashes, and periods, up to 35 characters.
Importantly and uniquely, you can also use URL parameters to build dynamic paths – more on that below.
✨ Tip: It's possible to have multiple HTTP methods respond from the same path. For example:
get /contact-us
andpost /contact-us
is totally valid, as you'd expect.
By default, your app's root is greedy – which means that unless specified, all paths and HTTP methods will invoke it. Any HTTP functions you define manually will be prioritized over the root. For example:
get /
specified: submitting a POST
request to /foo
will invoke src/http/get-index
get /
and post /foo
specified: submitting the same request will invoke src/http/post-foo
The greedy root also means you can run large amounts of your application's logic from a single get /
HTTP function. However, we don't advise it! One of the key advantages to building with cloud functions is their inherent isolation: many smaller functions means greater ease in debugging and faster deploys.
It's possible to build dynamic paths using Express-style URL parameters, like: get /shop/:product
URL parameters are passed to your route via the req.pathParameters
object. (Learn more about HTTP requests here.)
For example, when a client requests the path /shop/chocolate-chip-cookies
, the HTTP function handling that route receives a req
object containing:
{
routeKey: 'GET /shop/{product}',
rawPath: '/shop/chocolate-chip-cookies',
pathParameters: {
product: 'chocolate-chip-cookies'
}
}
You can do a lot with this functionality!
Note: Slashes still function as path part delimiters within URL params, so
get /api/:foo
will serviceget /api/hello
, but will not serviceget /api/hello/there
. To handleget /api/hello/there
, create a second HTTP function forget /api/:foo/:bar
You can remove HTTP functions from your app the same way you add them: by modifying your Architect project manifest (app.arc
) file.
Once pushed to your repo, any routes removed from your project's @http
pragma will be removed from staging
environment; your production
routes will not be changed until you deploy to production.
Note: Removing routes from your project will not result in any changes to your project's files, so you will find the
src/http/
folder still retains your HTTP function code (until you're ready to destroy it).