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:

export function <prefix>_<functionName>(request) { }

javascript | Copy Code

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.

import {ok, notFound, serverError} from 'wix-http-functions';
import wixData from 'wix-data';

// URL looks like:
// https://www.mysite.com/_functions/myFunction/John/Doe
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/John/Doe
export function get_myFunction(request) {
  const options = {
    headers: {
      'Content-Type': 'application/json'
    }
  };
  // query a collection to find matching items
  return wixData.query('myProductInventory')
    .eq('firstName', request.path[0])
    .eq('lastName', request.path[1])
    .find()
    .then( (results) => {
      // matching items were found
      if(results.items.length > 0) {
        options.body = {
          items: results.items
        };
        return ok(options);
      }
      // no matching items found
      options.body = {
        error: `${request.path[0]} ${request.path[1]} wasn't found`
      };
      return notFound(options);
    } )
    // something went wrong
    .catch( (error) => {
      options.body = {
        error: error
      };
      return serverError(options);
    } );
}

javascript | Copy Code

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

Premium sites:

https://www.{user_domain}/_functions/{functionName}

Copy Code

Free sites:

https://{user_name}.wixsite.com/{site_name}/_functions/{functionName}

Copy Code

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

Premium sites:

https://www.{user_domain}/_functions-dev/{functionName}

Copy Code

Free sites:

https://{user_name}.wixsite.com/{site_name}/_functions-dev/{functionName}

Copy Code

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.

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.

import {ok, badRequest} from 'wix-http-functions';
import {getSecret} from 'wix-secrets-backend';


// This function compares the authorization key provided in the 
// request headers with the secret key stored in the Secrets Manager.
async function isPermitted(headers){
  try{
    const authHeader = headers.auth;
    const sharedAuthKey = await getSecret('secretEmail');
    if (authHeader === sharedAuthKey) {
      return true;
    }
    return false;
  } 
  catch(err){
    console.error(err);
    return false
  }
}  

export async function get_functionName(request) {
  const headers = request.headers;
  if (!await isPermitted(headers)) {
    const options = {
      body: {
        error: 'Not authorized',
      },
      headers: {
        'Content-Type': 'application/json'
      }
    };
    return badRequest(options);
  }
  // Code for authorized requests...

  const response = {
    headers: {
      'Content-Type': 'application/json'
    }
  };
  response.body = {
    results: result
  };
  return ok(response);
}

javascript | Copy Code

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?

Introduction

Add HTTP Functions to Your Site

Keep Your Site Secure

In This Article