Velo: Expose a Site API with HTTP Functions
Using Velo you can create functions to expose the functionality of your site as a service. That means other people can use the functionality of your site by writing code that calls your site's API as defined by the Wix functions you create.
Important:
- The HTTP Functions 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.
- HTTP functions, when invoked using the endpoints in this article, run with the permissions of an anonymous site visitor.
- Use the HTTP Functions API or the
http-functions
SDK to call your HTTP functions with authentication context.
You might want to use HTTP functions to:
- Integrate your site with an automation tool, such as Zapier or IFTTT.
- Receive notifications and information from external webhooks.
- Share a backend between your site and a native mobile application.
Step 1 | Create the HTTP function
To create an API function for your site:
-
In your site's backend, create a file named http-functions.js.
-
Define the HTTP function using the following pattern:
Copy1Replace
<prefix>
withget
,post
,put
,delete
, oruse
, and<functionName>
with any name of your choice. The function name that you choose is included in the endpoint path.
Inside an HTTP function, you can write the logic to handle an incoming request and return an appropriate response. The function receives a WixHttpFunctionRequest
object that contains information about the incoming request. The function must return a WixHttpFunctionResponse
. There are a number of functions you can use to create the WixHttpFunctionResponse
, such as response()
, ok()
, created()
, notFound()
, serverError()
, badRequest()
, and forbidden()
.
For more information, see the API reference for Wix HTTP Functions.
get( )
This function responds to requests made with the HTTP GET method. Usually, it is called by consumers to retrieve a resource and should have no other effect. If defined in this way and the resource is found, your function should respond with a 200 (OK) status code and the requested resource.
Example: Create a GET HTTP function that queries a collection to find items based on the path of the request.
1
post( )
This function responds to requests made with the HTTP POST method. Usually, it is called by consumers to create a new resource. If defined in this way and the resource is created, your function should respond with a 201 (Created) status code and usually a reference to the new resource.
Example: Create a POST HTTP function that inserts an item from the request's body into a collection.
1
put( )
This function responds to requests made with the HTTP PUT method. Usually, it is called by consumers to update an existing resource. If defined in this way and the resource is updated, your function should respond with a 200 (OK) status code. If defined in this way and the resource did is created because it did not exist, your function should respond with a 201 (Created) status code.
Example: Create a PUT HTTP function that updates an item from the request's body in a collection.
1
delete( )
This function responds to requests made with the HTTP DELETE method. Usually, it is called by consumers to delete an existing resource. If defined in this way and the resource is deleted, your function should respond with a 200 (OK) status code.
Example: Create a DELETE HTTP function that deletes an item from a collection based on the path of the request.
1
use( )
This function responds to requests made with any of the GET, POST, PUT, or DELETE HTTP methods unless another function is defined specifically for the request's HTTP method.
For example, if you create functions named get_myFunction
and use_myFunction
, GET calls to myFunction will be handled by get_myFunction
, while POST, PUT, and DELETE calls will be handled by use_myFunction
.
Step 2 | Test and access the API endpoint
You can access your HTTP functions through various endpoints. Testing endpoints reflect the latest changes on a test site and differ from production endpoints. This behavior allows you to test changes before publishing them to production and means that calling different endpoints may yield different results.
Note:
- For changes to testing endpoints to take effect, create or deploy a test site.
- For changes to production endpoints to take effect, publish your site.
- By default, calls to your site's HTTP endpoints don't have authentication context. To call your HTTP endpoints with authentication context, use the HTTP Functions API or the
http-functions
SDK.
Testing
To test your HTTP functions, create or deploy a test site and call the following endpoints:
- For premium sites:
https://www.{user\_domain}/\_functions/<functionName>?rc=test-site
. - For free sites:
https://{user\_name}.wixsite.com/{site\_name}/\_functions/<functionName>?rc=test-site
.
For sites using the Wix CLI, call the following endpoints:
- For premium sites:
https://www.{user\_domain}/\_functions/<functionName>?siteRevision=<revisionNumber>&branchId=<branchId>
. - For free sites:
https://username.wixsite.com/mysite/_functions/<functionName>?siteRevision=<revisionNumber>&branchId=<branchId>
.
Alternatively, you can use the following endpoints to test your HTTP functions in the editor preview. These endpoints access the latest code in the editor without deploying a test site, though this is less recommended:
- For premium sites:
https://www.{user\_domain}/\_functions-dev/<functionName>
. - For free sites:
https://{user\_name}.wixsite.com/{site\_name}/\_functions-dev/<functionName>
.
In addition, you can test your HTTP functions using Functional Testing, Git Integration to test your code in the local editor, or push your code to GitHub and run functional tests using the Wix code editor.
Production
Clients can access your HTTP functions using the following endpoints:
- For premium sites:
https://www.{user\_domain}/\_functions/<functionName>
. - For free sites:
https://{user\_name}.wixsite.com/{site\_name}/\_functions/<functionName>
.
Step 3 | Debug your code
Debug HTTP functions by adding console.log()
calls to your function code.
The information you log appears in the function output when using Functional Testing and in your site's Logs.
The information logged by code that runs on the backend can also be viewed as Wix Logs. Wix Logs are accessible via Developer Tools > Logging Tools on the site dashboard.