Proxy API

The Essepage Proxy API lets you call external APIs that are difficult to access directly from a browser through the Essepage server.

The Proxy API is useful in the following situations.

• The external API does not allow requests from your website because of its CORS policy
• The API requires a private API key or authentication token
• You do not want to expose the external API URL in browser code
• You need to manage shared request headers and default data on the server

When you use the Proxy API, the browser does not call the external API directly. The page calls a Proxy API created within the project using Essepage.fetch(), and the Essepage server forwards the request to the external API.

Essepage.fetch() on the page
↓
Essepage Proxy API
↓
External API
↓
Essepage Proxy API
↓
Use the data on the page

Why Use the Proxy API?

When you call an external API directly from a browser, the request is affected by the API’s CORS policy.

If the external API server does not allow requests from your website, you may see an error like this.

Access to fetch at 'https://api.example.com'
has been blocked by CORS policy.

You cannot change the external API’s CORS settings from JavaScript on your page.

Calling an API directly from the browser is also a security risk when the API requires an API key or authentication token.

fetch("https://api.example.com/data", {
    headers: {
        Authorization: "Bearer MY_SECRET_API_KEY",
    },
});

JavaScript written on a page is delivered to the visitor’s browser. Visitors can therefore inspect API keys and authentication tokens written in the code using browser developer tools.

The Essepage Proxy API calls the external API from the server, allowing you to separate the actual API URL and authentication information from the browser code.

Creating a Proxy API File

Suppose you want to create the following Proxy API.

/_api/ordered_list

Create the following file inside /public.

/public/_api/ordered_list/+fetch.json

The file structure will look like this.

/public
├── +page.essepage
└── _api
    └── ordered_list
        └── +fetch.json

The folder containing +fetch.json determines the Proxy API path used by the page.

Setting the External API URL

In +fetch.json, enter the external API URL that the Essepage server will call.

{
    "url": "https://api.example.com/orders"
}

For a basic Proxy API, you only need to set url.

url is the actual external API URL called by the Essepage server.

Save and publish the file.

1. Save /public/_api/ordered_list/+fetch.json.
2. Right-click the file.
3. Select Publish.
4. Wait for publishing to finish.

The +fetch.json file must be published before the page can call the Proxy API. Publishing the file does not display its contents to visitors.

Calling the Proxy API With Essepage.fetch()

On the page, use the Essepage-specific Essepage.fetch() function to call the Proxy API.

const result = await Essepage.fetch(
    "/_api/ordered_list"
);

The first argument is the Proxy API path associated with the +fetch.json file.

"/_api/ordered_list"

Do not enter the complete file path.

"/public/_api/ordered_list/+fetch.json"

/public and +fetch.json are not included in the request path.

Sending Data to the External API

To send data to the external API, use the second argument of Essepage.fetch().

const result = await Essepage.fetch(
    "/_api/ordered_list",
    {
        body: {
            phone_number: "111-2222-3333",
        },
    }
);

Values in the second argument are passed as request options when the external API is called.

This example sends the following data in the request body.

{
    "phone_number": "Phone number to search"
}

A complete page example looks like this.

<label for="phoneNumber">
    Phone Number
</label>

<input
    id="phoneNumber"
    type="tel"
>

<button id="searchButton">
    Search
</button>

<p id="message"></p>

<script>
    const phoneNumber = document.getElementById("phoneNumber");
    const searchButton = document.getElementById("searchButton");
    const message = document.getElementById("message");

    searchButton.addEventListener("click", async () => {
        const value = phoneNumber.value.trim();

        if (!value) {
            message.textContent = "Enter a phone number.";
            return;
        }

        try {
            const result = await Essepage.fetch(
                "/_api/ordered_list",
                {
                    body: {
                        phone_number: value,
                    },
                }
            );

            console.log(result);
            message.textContent = "The request was completed.";
        } catch (error) {
            console.error(error);
            message.textContent = "The request failed.";
        }
    });
</script>

The structure of the data returned by the external API depends on the API you use. Check the returned value in the console, and then display the data you need on the page.

Setting Default Request Options

You can use options in +fetch.json to set the default request options for the Proxy API.

{
    "url": "https://api.example.com/orders",
    "options": {
        "method": "POST",
        "credentials": "include",
        "headers": {
            "content-type": "application/json",
            "Accept": "application/json"
        },
        "body": {
            "title": "title"
        }
    }
}

Each item has the following purpose.

options provides the default values used when calling the Proxy API.

If you omit options, Essepage uses its built-in request options. The default request method is POST.

If you always use the same request method and headers, defining them in options in +fetch.json makes them easier to manage.

Overriding Default Options When Calling the API

The options in +fetch.json are used as default values. If you specify the same item in the second argument of Essepage.fetch(), the value provided at call time takes priority.

const result = await Essepage.fetch(
    "/_api/ordered_list",
    {
        body: {
            title: "My Product",
        },
    }
);

Request options are applied in the following order.

Essepage built-in request options
                ↓
options in +fetch.json
                ↓
Second argument of Essepage.fetch()

Settings lower in this list have higher priority.

For example, even if a default body is defined in +fetch.json, a different body passed to Essepage.fetch() takes priority.

This structure lets you manage shared request settings in +fetch.json while passing only the values that change with each request from the page.

Building API URLs With Global Variables

If you manage the base URL and endpoint of an external API as a global variable, you can use that value in url.

Create the following file in the project root.

/+globals.config.json

Define the global variable in +globals.config.json.

{
    "private_api_url": "https://api.example.com/private_api_endpoint"
}

Use the global variable in +fetch.json as follows.

{
    "url": "{{$ global : private_api_url $}}",
    "options": {
        "method": "POST",
        "credentials": "include",
        "headers": {
            "content-type": "application/json",
            "Accept": "application/json"
        }
    }
}

This is useful when multiple Proxy APIs use the same base URL or when you want to manage external API URLs in one place.

Proxy API Configuration Summary

The Proxy API file and page code serve the following purposes.

The basic workflow is as follows.

Create +fetch.json
        ↓
Set the external API URL
        ↓
Save and publish the file
        ↓
Call it with Essepage.fetch()
        ↓
Check the result and errors

Updating a Proxy API

If you modify a published +fetch.json file, apply the changes as you would with other files.

1. Edit +fetch.json.
2. Save the file.
3. Select Apply Changes.
4. Call the Proxy API again from the page.
5. Check the result in the editor console.

It may take some time for the cache to update after applying changes.

When the Proxy API Does Not Work

If the Proxy API does not work as expected, check the following.

• The +fetch.json file is in the correct location
• The file has been saved and published
• url contains the correct external API URL
• +fetch.json uses valid JSON syntax
• The first argument of Essepage.fetch() matches the file path
• The request method and headers meet the requirements of the external API
• body contains the required values
• The global variable name and value are correct
• The external API server is responding normally

If an error occurs, check the message in the editor console.

Next Steps

Once you understand how to connect an external API using the Proxy API, continue with the following guides.

• Check JavaScript messages and errors: Console and Debugging
• Move JavaScript code into a separate file: Including Files
• Manage shared settings and global variables: Configuration
• Apply saved changes to the public site: Save, Publish, and Apply