Migrate from Web Methods to HTTP Endpoints

Migrate web methods to HTTP endpoints in your new Wix CLI project, as part of migrating an app from the legacy Wix CLI.

Folder structure

A legacy .web.ts file is named after its module and can export several web methods. An endpoint file is named after the route it serves and holds the handlers of that route. Step 1 explains how to map one to the other.

Step 1 | Relocate your web method files

To relocate your web methods:

1. In your new Wix CLI project, create an endpoint file in src/api/ for each web method, or for each resource, as described below. The file name sets the route, so src/api/multiply.ts serves /multiply.
2. If your web methods import shared backend modules, copy those modules into src/lib/ in the new project, and update the import paths. Shared modules aren't extensions, so they don't belong under src/api/.
3. If a .web.ts file also exports functions that aren't web methods, don't turn them into endpoints. If other backend code uses them, move them into a shared module in src/lib/. If nothing uses them, leave them out.
4. Shared code outside src/backend/ that both your backend and your extensions import, such as src/consts.ts or src/types.ts, keeps its path. See Migrate the backend in the main migration guide.

If one legacy file exports several web methods, you can't map them all into a single endpoint file, because an endpoint file exports at most 1 handler per HTTP method. Choose one of the following:

• Create one endpoint file per web method.
• Create a single endpoint file for the resource, and give each operation a different HTTP method, for example GET to read, POST to update, and DELETE to clear.

Step 2 | Replace the import statement

Replace the @wix/web-methods import statement with the APIRoute type.

For example, the web method file uses this import:

HTTP endpoints use the following import:

Step 3 | Replace web method exports

To replace your web method exports:

1. Replace each webMethod() export with an HTTP method handler.
2. Each handler receives a request object. Read arguments from the request object. For example, extract values from the query string for GET requests, or from the request body for POST requests.
3. Implement the relevant logic and return a Response object with the result.
4. Return a Response on every path through the handler, including error paths. The APIRoute type requires it, so the typecheck fails with Type '...' is not assignable to type 'APIRoute' for a handler that returns anything else on some path. For a web method that returns nothing, return new Response(null, { status: 204 }).

For example, the web method file exports the following:

The corresponding HTTP endpoint exports the following:

Step 4 | Manage permissions

Web methods specify permissions using the Permissions enum from @wix/web-methods. HTTP endpoints have no equivalent setting, so an endpoint is reachable by any caller until you check the caller yourself. To restrict access, use Get Token Info to read the caller's token and inspect its subjectType.

The following table shows the check to add for each permission:

For example, the following web method limits access to site members:

Enforce the same permissions in an HTTP endpoint as follows:

Update your frontend call sites as you migrate each extension

The steps above move your backend code. Your frontend call sites stay in the legacy project until you migrate the extension that holds them, so there's nothing to change here yet.

Come back to this section from Add the extension to the new project in the main migration guide, once the extension's code is in the new project. Then replace its web method imports with HTTP calls.

For example, the web method is called from the frontend as follows:

Call an HTTP endpoint from the frontend as follows. A web method call returns a typed value and throws on failure, while an HTTP call returns a Response, so check res.ok and type the parsed body yourself:

Full example

The following is a full example of migrating web methods to HTTP endpoints on the backend and frontend.

Backend example

This example shows the backend implementation of a web method in your legacy project's src/backend/ directory:

The equivalent HTTP endpoint is in your new Wix CLI project's src/api/ directory:

Frontend example

This example shows a web method called from the frontend:

The equivalent HTTP endpoint is called from the frontend as follows: