🔢Operating and Running a Data Proxy

Below is a step-by-step guide to initializing and running a Data Proxy to the SEDA Network

Running a proxy node

For more information on the proxy node architecture checkout the Data Proxy overview.

Prerequisites

Install Bun:

curl -fsSL https://bun.sh/install | bash

Clone the Data Proxy directory:

git clone https://github.com/sedaprotocol/seda-data-proxy.git ./my-project

Install the project dependencies:

cd ./my-project

bun install 

Checkout the CLI commands:

bun start --help

Running a node

Note: The SEDA network won't be able to access your proxy node unless you expose it on a public IP or domain.

Start by generating the config.json (mandatory) and data-proxy-private-key.json (optional). The private key will be used for for signing data, which is optional but recommended, and can also be passed in as the following environment variable: SEDA_DATA_PROXY_PRIVATE_KEY.

bun start init

{
    "routeGroup": "proxy", // Will host at myproxy.com/proxy
    "routes": [
        {
            "path": "/*",
            "upstreamUrl": "https://.myapi.com/endpoint/{*}", // {*} will be string replaced with user's api endpoint
            "headers": {
                "x--api-key": "MY-API-KEY",
                "accept": "application/json"
            }
        }
    ]
}

To start your proxy run the following command:

# Disables the proofing mechanism so it's easier to debug the proxy
bun start run --disable-proof

# The console will output something similiar:
2024-08-19 13:21:46.624 info: Proxy routes is at <http://127.0.0.1:5384/proxy/>

Your proxy now running!

Additional configuration

Multiple routes:

{
  "routeGroup": "proxy",
  "routes": [
    {
      "path": "/eth-usd",
      "upstreamUrl": "<https://myapi.com/eth-usd>",
      // Default is GET
      "headers": {
        "x-api-key": "some-api-key",
      },
    },
    {
      "path": "/btc-usd",
      "upstreamUrl": "<https://myapi.com/btc-usd>",
      // Allows for multiple method setting
      "method": ["GET", "HEAD"],
      "headers": {
        "x-api-key": "some-api-key",
      },
    },
  ],
}

Variables

The config.json has support for using variable routes by using :varName:

{
  "routeGroup": "proxy",
  "routes": [
    {
      "path": "/:coinA/:coinB",
      // Use {} to inject route variables
      "upstreamUrl": "<https://myapi.com/{:coinA}-{:coinB}>",
      "headers": {
        "x-api-key": "some-api-key",
        // Can also be injected in the header
        "x-custom": "{:coinA}",
      },
    },
  ],
}

JSON path

If you don't want to expose all API info you can use jsonPath to reduce the response:

{
  "routeGroup": "proxy",
  "routes": [
    {
      "path": "/planets/:planet",
      "upstreamUrl": "<https://swapi.dev/api/planets/{:planet}>",
      // Calling the API <http://localhost:5384/proxy/planets/1> will only return "Tatooine" and omit the rest
      "jsonPath": "$.name",
      "headers": {
        "x-api-key": "some-api-key",
      },
    },
  ],
}

Fowarding headers

By default the data proxy node will only forward the content-type as a response. This can be configured to include more headers if desired:

{
  "routeGroup": "proxy",
  "routes": [
    {
      "path": "/planets/:planet",
      "upstreamUrl": "<https://swapi.dev/api/planets/{:planet}>",
      // Now the API will also return the server header from SWApi
      "forwardRepsonseHeaders": ["content-type", "server"],
      "headers": {
        "x-api-key": "some-api-key",
      },
    },
  ],
}

Environment variables injection

Sometimes you don't want to expose your API key in a config file, or you have multiple environments running. The Data Proxy node has support for injecting environment variables through {$MY_ENV_VARIABLE}:

{
  "routeGroup": "proxy",
  "routes": [
    {
      // Everything will be injected in the URL
      "path": "/*",
      "upstreamUrl": "<https://swapi.dev/api/{*}>",
      "headers": {
        "x-api-key": "{$SECRET_API_KEY}",
      },
    },
  ],
}

Wildcard routes

The Data Proxy node has support for wildcard routes, which allows you to quickly expose all your APIs:

{
  "routeGroup": "proxy",
  "routes": [
    {
      // Everything will be injected in the URL
      "path": "/*",
      "upstreamUrl": "https://swapi.dev/api/{*}",
      "headers": {
        "x-api-key": "some-api-key",
      },
    },
  ],
}