CorvidReference

wix-http-functions

HTTP functions are used to expose an API of your site's functionality.

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.

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) { }

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.

 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) {
   let options = {
     "headers": {
       "Content-Type": "application/json"
     }
   };
   // query a collection to find matching items
   return wixData.query("myUsersCollection")
     .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);
     } );
 }

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

Premium sites:

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

Free sites:

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

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

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Table of Contents

FUNCTIONS

?
Perform actions on an object.
badRequest( )Returns a response with status code 400 (Bad Request) and the information from the options parameter.
created( )Returns a response with status code 201 (Created) and the information from the options parameter.
delete( )A function that responds to requests made with the HTTP DELETE method.
forbidden( )Returns a response with status code 403 (Forbidden) and the information from the options parameter.
get( )A function that responds to requests made with the HTTP GET method.
notFound( )Returns a response with status code 404 (Not Found) and the information from the options parameter.
ok( )Returns a response with status code 200 (OK) and the information from the options parameter.
options( )A function that responds to requests made with the HTTP OPTIONS method.
post( )A function that responds to requests made with the HTTP POST method.
put( )A function that responds to requests made with the HTTP PUT method.
response( )

Returns a response populated with the information from the options parameter. The response() function creates a custom response built with the information passed to the options parameter in a WixHttpFunctionResponseOptions object.

Use the response() function to create a response to return from an HTTP function.

serverError( )Returns a response with status code 500 (Internal Server Error) and the information from the options parameter.
use( )A function that responds to requests made with any HTTP method.

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
WixHttpFunctionResponseOptionsAn object used to customize a response to an HTTP function call.

Related Content

FAQ

    How do I debug an HTTP function?
    How do I bypass collection permissions so I can access my collections from an HTTP function?
    What can I do with HTTP functions?

badRequest( )

Returns a response with status code 400 (Bad Request) and the information from the options parameter.

Description

The badRequest() function creates a response with the status code 400 (Bad Request).

Optionally, the badRequest() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the badRequest() function to create a response to return from an HTTP function. A 400 (Bad Request) response is usually used to indicate the request was unsuccessful because of a client error, such as a request using the incorrent syntax.

Syntax

function badRequest(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 400 (Bad Request) response

// In http-functions.js

import {badRequest} from 'wix-http-functions';

export function use_myFunction(request) {

  return badRequest();
}

Create a 400 (Bad Request) response

// In http-functions.js

import {badRequest} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "error": "The request must contain the 'X' parameter."
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return badRequest(options);
}

created( )

Returns a response with status code 201 (Created) and the information from the options parameter.

Description

The created() function creates a response with the status code 201 (Created).

Optionally, the created() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the created() function to create a response to return from an HTTP function. A 201 (Created) response is usually used to indicate that the request was successful and a new resource has been created.

Syntax

function created(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 201 (Created) response

// In http-functions.js

import {created} from 'wix-http-functions';

export function use_myFunction(request) {

  return created();
}

Create a 201 (Created) response

// In http-functions.js

import {created} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "key1": "value1",
      "key2": "value2"
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return created(options);
}

delete( )

A function that responds to requests made with the HTTP DELETE method.

Description

The HTTP DELETE method is usually called by consumers to delete an existing resource. If defined in this way and the resource is deleted, the function should respond with a 200 (OK) status code.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The delete() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All DELETE requests with the following URL will be routed to this function:

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function delete(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create a DELETE HTTP function

This example creates a DELETE HTTP function named myFunction.
// In http-functions.js

import {ok} from 'wix-http-functions';

// URL looks like:
// https://www.mysite.com/_functions/myFunction/someId
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/someId
export function delete_myFunction(request) {

  const toRemove = request.path[0];

  // remove the resource

  return ok();
}

Create a DELETE HTTP function

This example creates a DELETE HTTP function named myFunction that deletes an item from a collection named myCollection based on the path of the request. If the item is deleted successfully, an OK response is returned.

// In http-functions.js

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

// URL looks like:
// https://www.mysite.com/_functions/myFunction/76bf-8bfa-714
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/76bf-8bfa-714
export function delete_myFunction(request) {
  let options = {
    "headers": {
      "Content-Type": "application/json"
    }
  };
  // delete the item from a collection
  return wixData.remove("myCollection", request.path[0])
    .then( (results) => {
      options.body = {
        "deleted": results
      };
      return ok(options);
    } )
    // something went wrong
    .catch( (error) => {
      options.body = {
        "error": error
      };
      return serverError(options);
    } );
}

forbidden( )

Returns a response with status code 403 (Forbidden) and the information from the options parameter.

Description

The forbidden() function creates a response with the status code 403 (Forbidden).

Optionally, the forbidden() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the forbidden() function to create a response to return from an HTTP function. A 403 (Forbidden) response is used to indicate the request was valid but the server is refusing to process it, usually because the client does not have the necessary permissions for the requested resource.

Syntax

function forbidden(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 403 (Forbidden) response

// In http-functions.js

import {forbidden} from 'wix-http-functions';

export function use_myFunction(request) {

  return forbidden();
}

Create a 403 (Forbidden) response

// In http-functions.js

import {forbidden} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "error": "forbidden",
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return forbidden(options);
}

get( )

A function that responds to requests made with the HTTP GET method.

Description

The HTTP GET method is usually called by consumers to retrieve a resource and should have no other effect. If used in this way and the resource is found, the function should respond with a 200 (OK) status code and the requested resource.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The get() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All GET requests with the following URL will be routed to this function:

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function get(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create a GET HTTP function

This example creates a GET HTTP function named myFunction.
// In http-functions.js

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

// URL looks like:
// https://www.mysite.com/_functions/myFunction/findMe
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/findMe
export function get_myFunction(request) {
  if(request.path[0] === "findMe") {
    const body = "Found it!";
    return ok({body: body});
  }

  const body = "Can't find it!";
  return notFound({body: body});
}

Create a GET HTTP function

This example creates a GET HTTP function named myFunction that queries a collection named myCollection 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.

// In http-functions.js

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) {
  let options = {
    "headers": {
      "Content-Type": "application/json"
    }
  };
  // query a collection to find matching items
  return wixData.query("myUsersCollection")
    .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]}' was not found`
      };
      return notFound(options);
    } )
    // something went wrong
    .catch( (error) => {
      options.body = {
        "error": error
      };
      return serverError(options);
    } );
}

notFound( )

Returns a response with status code 404 (Not Found) and the information from the options parameter.

Description

The notFound() function creates a response with the status code 404 (Not Found).

Optionally, the notFound() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the notFound() function to create a response to return from an HTTP function. A 404 (Not Found) response is usually used to indicate that the requested was not found at the current time.

Syntax

function notFound(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 404 (Not Found) response

// In http-functions.js

import {notFound} from 'wix-http-functions';

export function use_myFunction(request) {

  return notFound();
}

Create a 404 (Not Found) response

// In http-functions.js

import {notFound} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "error": "not found"
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return notFound(options);
}

ok( )

Returns a response with status code 200 (OK) and the information from the options parameter.

Description

The ok() function creates a response with the status code 200 (OK).

Optionally, the ok() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the response() function to create a response to return from an HTTP function. A 200 (OK) response is usually used to indicate that a request was successful.

Syntax

function ok(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 200 (OK) response

// In http-functions.js

import {ok} from 'wix-http-functions';

export function use_myFunction(request) {

  return ok();
}

Create a 200 (OK) response

// In http-functions.js

import {ok} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "key1": "value1",
      "key2": "value2"
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return ok(options);
}

options( )

A function that responds to requests made with the HTTP OPTIONS method.

Description

The HTTP OPTIONS method is usually called by consumers attempting to identify the allowed request methods or as part of a CORS preflight request. If defined in this way, the function should respond with a 204 (No Content) status code and header data that indicates which methods are allowed and from which origins.

Respond to the request by returning a WixHttpFunctionResponse object you create using the response() function.

The options() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All OPTIONS requests with the following URL will be routed to this function:

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function options(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create an OPTIONS HTTP function

This example creates an OPTIONS HTTP function named myFunction.
// In http-functions.js

import {response} from 'wix-http-functions';

// URL looks like:
// https://www.mysite.com/_functions/myFunction/
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/

export function options_myFunction(request) {
  let headers = {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
      "Access-Control-Max-Age": "86400"
  }
  return response({"status": 204, "headers": headers});
}

post( )

A function that responds to requests made with the HTTP POST method.

Description

The HTTP POST method is usually called by consumers to create a new resource. If defined in this way and the resource is created, the function should respond with a 201 (Created) status code and usually a reference to the new resource.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The post() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All POST requests with the following URL will be routed to this function:

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function post(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create a POST HTTP function

This example creates a POST HTTP function named myFunction.
// In http-functions.js

import {created} from 'wix-http-functions';

// URL looks like:
// https://www.mysite.com/_functions/myFunction/
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/
export function post_myFunction(request) {

  return request.body.text()
    .then( (body) => {

      // insert the info from the body somewhere

      return created();
    } );
}

Create a POST HTTP function

This example creates a POST HTTP function named myFunction that inserts an item from the request's body into a collection named myCollection. If the item is inserted successfully, a Created response is returned.

// In http-functions.js

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

// URL looks like:
// https://www.mysite.com/_functions/myFunction/
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/
export function post_myFunction(request) {
  let options = {
    "headers": {
      "Content-Type": "application/json"
    }
  };
  // get the request body
  return request.body.json()
  .then( (body) => {
      // insert the item in a collection
      return wixData.insert("myCollection", body);
    } )
    .then( (results) => {
      options.body = {
        "inserted": results
      };
      return created(options);
    } )
    // something went wrong
    .catch( (error) => {
      options.body = {
        "error": error
      };
      return serverError(options);
    } );
}

put( )

A function that responds to requests made with the HTTP PUT method.

Description

The HTTP PUT method is usually called by consumers to update an existing resource.

If defined in this way and the resource is updated, the function should respond with a 200 (OK) status code. If defined in this way and the resource is created because it did not exist, you should respond with a 201 (Created) status code.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The put() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All PUT requests with the following URL will be routed to this function:

Premium sites:

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

Free sites:

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

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function put(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create a PUT HTTP function

This example creates a PUT HTTP function named myFunction.
// In http-functions.js

import {ok} from 'wix-http-functions';

// URL looks like:
// https://www.mysite.com/_functions/myFunction/
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/
export function put_myFunction(request) {

  return request.body.text()
    .then( (body) => {

      // update the info from the body somewhere
      return ok();
    } );
}

Create a PUT HTTP function

This example creates a PUT HTTP function named myFunction that updates an item from the request's body in a collection named myCollection. If the item is updated successfully, an OK response is returned.

// In http-functions.js

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

// URL looks like:
// https://www.mysite.com/_functions/myFunction/
// or:
// https://user.wixsite.com/mysite/_functions/myFunction/
export function put_myFunction(request) {
  let options = {
    "headers": {
      "Content-Type": "application/json"
    }
  };
  // get the request body
  return request.body.json()
  .then( (body) => {
      // update the item in a collection
      return wixData.update("myCollection", body);
    } )
    .then( (results) => {
      options.body = {
        "inserted": results
      };
      return ok(options);
    } )
    // something went wrong
    .catch( (error) => {
      options.body = {
        "error": error
      };
      return serverError(options);
    } );
}

response( )

Returns a response populated with the information from the options parameter. The response() function creates a custom response built with the information passed to the options parameter in a WixHttpFunctionResponseOptions object.

Use the response() function to create a response to return from an HTTP function.

Syntax

function response(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a response

// In http-functions.js

import {response} from 'wix-http-functions';

export function use_myFunction(request) {

  return response();
}

Create a response

// In http-functions.js

import {response} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    status: 418,
    body: {
      "key1": "value1",
      "key2": "value2"
    },
    headers: {
      "Content-Type": "application/json"
    }
  };

  return response(options);
}

serverError( )

Returns a response with status code 500 (Internal Server Error) and the information from the options parameter.

Description

The serverError() function creates a response with the status code 500 (Internal Server Error).

Optionally, the serverError() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers. If the object contains a status it will be ignored.

Use the serverError() function to create a response to return from an HTTP function. A 500 (Internal Server Error) response is usually used to indicate the request was unsuccessful because of an unexpected error on the server.

Syntax

function serverError(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse

Examples

Create a 500 (Internal Server Error) response

// In http-functions.js

import {serverError} from 'wix-http-functions';

export function use_myFunction(request) {

  return serverError(options);
}

Create a 500 (Internal Server Error) response

// In http-functions.js

import {serverError} from 'wix-http-functions';

export function use_myFunction(request) {

  let options = {
    body: {
      "error": "internal server error",
    },
    headers: {
      "Content-Type": "application/json"
    }
  }

  return serverError(options);
}

use( )

A function that responds to requests made with any HTTP method.

Description

Requests made with any of the GET, POST, PUT, DELETE, or OPTIONS HTTP methods will be routed to this function 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, DELETE, and OPTIONS calls will be handled by use_myFunction.

The use() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All GET, POST, PUT, DELETE, and OPTIONS HTTP requests with the following URL will be routed to this function unless another function is defined specifically for the request's HTTP method:

Premium sites:

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

Free sites:

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

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

Note

You must publish your site at least once before using both the testing and production endpoints. After that, you save your site for changes you make to testing endpoints to take effect and you publish your site for changes you make to the production endpoints to take effect.

Syntax

function use(request: WixHttpFunctionRequest): WixHttpFunctionResponse

Examples

Create a catchall HTTP function

This example creates a catchall HTTP function named myFunction.
// In http-functions.js

import {ok} from 'wix-http-functions';

export function use_myFunction(request) {

  const method = request.method;

  // ...

  return ok();
}

WixHttpFunctionResponseOptions

An object used to customize a response to an HTTP function call.

Syntax

type WixHttpFunctionResponseOptions = {
  status: number
  body: string | Buffer
  headers: Object
}
MEMBERS
?
The properties of an object.
status(Optional)
number
The response's HTTP status code.
body(Optional)
string | Buffer
The response's body.
headers(Optional)
Object
The response's header fields. The headers property contains an object of key:value pairs where the key is the header field name and the value is the header field value.