Introduction

HTTP functions allow you to expose the functionality of your site as a service. That means other people can write code to consume the functionality you expose by calling the functions of the API that you define.

Important: This API is only intended for use in server-to-server communications. If you use this API to set a cookie on a site visitor's browser you may no longer be in compliance with applicable data privacy regulations.

To learn more about HTTP functions, see Exposing a Site API with HTTP Functions.

Add HTTP Functions to Your Site

To add an HTTP function, add a file named http-functions.js to the Backend section of your site. The code for your HTTP functions is added to that file.

HTTP functions are defined using the following pattern:

Copy
1

Where <prefix> is one of get, post, put, delete, options, or use and <functionName> is the name users use to reach your function.

These are not functions that you call in your code, rather they are functions that you define. They are called when your users make HTTP requests using the associated URLs as described below.

For example, the following code creates a function that responds to GET requests by querying a collection to find items based on the path of the request. If matching items are found, an OK response is returned. If no matches are found, a Not Found response is returned.

Warning: This code is an example for educational purposes only. It's not secure, and using it can leave your site's data exposed. To learn about securing your HTTP endpoints, see Keep Your Site Secure.

Copy
1

Clients consume your HTTP functions by reaching endpoints with the following patterns.

Premium sites:

Copy
1

Free sites:

Copy
1

You test your HTTP functions by reaching endpoints using the following patterns.

Premium sites:

Copy
1

Free sites:

Copy
1

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Authentication Context

The above endpoints don't send authentication context to your HTTP functions. Authentication context is information about who is calling an API. This means every Velo API call inside your HTTP function is treated as if an anonymous site visitor is making the call. This restricts the Velo functions you can use in your code without overriding authentication using elevate().

To call your HTTP functions with authentication context, use the HTTP Functions API or the http-functions SDK. This allows you to:

  • Authorize only users with the right permissions for each Velo function, such as admins or site members.
  • Use functions that return different responses based on the user who calls them, such as getCurrentMember().

You can also use the elevate() function in your HTTP functions to bypass permissions. Exercise caution when using this function to prevent security vulnerabilities.

Keep Your Site Secure

HTTP functions expose your site's data and functionality to anyone making requests to your endpoints. You can keep your site secure by authenticating requests. For example, the following code retrieves a secret key from the 'auth' property in a request's headers. This key is compared to one stored in the site's Secrets Manager using the Secrets API. If the keys match, the request is authenticated.

Copy
1

Valid requests to this endpoint must now include "auth" : "My-Secret-Key" in their headers section.

If another Wix site is sending requests to your endpoints, you can use the HMAC Authentication Velo package for even more security.

Was this helpful?
Yes
No