Skip to content

Commit

Permalink
docs(data-proxy): update config docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Thomasvdam
Thomasvdam committed Nov 4, 2024
1 parent 988bf78 commit 1a5a0ba
Showing 1 changed file with 74 additions and 50 deletions.
124 changes: 74 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,79 +63,104 @@ The node will auto sign the response and include two headers: `x-seda-signature`

## Configuration

The config file allows you to configure multiple routes:
### Route Group

All proxy routes are grouped under a single path prefix, by default this is "proxy". You can change this by specifying the `routeGroup` attribute in the config.json:

```jsonc
{
"routeGroup": "custom"
// Rest of config
}
```

### Multiple routes

A single data proxy can expose different data sources through a simple mapping in the config.json. The `routes` attribute takes an array of proxy route objects which can each have their own configuration.

The two required attributes are `path` and `upstreamUrl`. These specify how the proxy should be called and how the proxy should call the upstream. By default a route is configured as `GET`, but optionally you can specify which methods the route should support with the `methods` attribute.

```jsonc
{
"routeGroup": "proxy",
"routes": [
{
"path": "/eth-usd",
"upstreamUrl": "https://myapi.com/eth-usd",
// Default is GET
"headers": {
"x-api-key": "some-api-key"
}
"upstreamUrl": "https://myapi.com/eth-usd"
// Default method is GET
},
{
"path": "/btc-usd",
"upstreamUrl": "https://myapi.com/btc-usd",
// Allows for multiple method setting
"method": ["GET", "HEAD"],
"headers": {
"x-api-key": "some-api-key"
}
// You can set multiple methods for the same route
"method": ["GET", "HEAD"]
}
]
}
```

### Variables
### Upstream Request Headers

The config.json has support for using variable routes by using `:varName`:
Should your upstream require certain request headers you can configure those in the `routes` object. All headers specified in the `headers` attribute will be sent to the upstream in addition to headers specified by the original request.

```jsonc
{
"routeGroup": "proxy",
"routes": [
{
"path": "/:coinA/:coinB",
// Use {} to inject route variables
"upstreamUrl": "https://myapi.com/{:coinA}-{:coinB}",
"path": "/eth",
"upstreamUrl": "https://myapi.com/endpoint/eth",
"headers": {
"x-api-key": "some-api-key",
// Can also be injected in the header
"x-custom": "{:coinA}"
"x-api-key": "MY-API-KEY",
"accept": "application/json"
}
}
]
}
```

### JSON Path
### Environment Variable Injection

If you don't want to expose all API info you can use `jsonPath` to reduce the response:
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 the `{$MY_ENV_VARIABLE}` syntax:

```jsonc
{
"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",
"path": "/odds",
"upstreamUrl": "https://swapi.dev/api/my-odds",
"headers": {
"x-api-key": "some-api-key"
"x-api-key": "{$SECRET_API_KEY}"
}
}
]
}
```

### Forwarding headers
> [!WARNING]
> Environment variables are evaluated during startup of the data proxy. If it detects variables in the config which aren't present in the environment the process will exit with an error message detailing which environment variable it was unable to find.
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:
### Path Parameters

The `routes` objects have support for path parameter variables and forwarding those to the upstream. Simply declare a variable in your path with the `:varName:` syntax and reference them in the upstreamUrl with the `{:varName:}` syntax. See below for an example:

```jsonc
{
"routeGroup": "proxy",
"routes": [
{
"path": "/:coinA/:coinB",
// Use {} to inject route variables
"upstreamUrl": "https://myapi.com/{:coinA}-{:coinB}"
}
]
}
```

### Forwarding Response Headers

By default the data proxy node will only forward the `content-type` header from the upstream response. If required you can specify which other headers the proxy should forward to the requesting client:

```jsonc
{
Expand All @@ -154,38 +179,39 @@ By default the data proxy node will only forward the `content-type` as a respons
}
```

### Environment variables injection
### Wildcard Routes

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}`:
The Data Proxy node has support for wildcard routes, which allows you to quickly expose all your APIs:

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

### Wildcard routes
### JSON Path

The Data Proxy node has support for wildcard routes, which allows you to quickly expose all your APIs:
If you don't want to expose all API info you can use `jsonPath` to return a subset of the response:

```jsonc
{
"routeGroup": "proxy",
"routes": [
{
// Everything will be injected in the URL
"path": "/*",
"upstreamUrl": "https://swapi.dev/api/{*}",
"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"
}
Expand All @@ -194,16 +220,15 @@ The Data Proxy node has support for wildcard routes, which allows you to quickly
}
```

## Status endpoints
### Status Endpoint

The Data Proxy node has support for exposing status information through some endpoints. This can be used to monitor the health of the node and the number of requests it has processed.

The status endpoint has two routes:

- `/<statusEndpointsRoot>/health`
Returns a JSON object with the following structure:

```json
- `/status/health`
Returns a JSON object with the following strucuture:
```jsonc
{
"status": "healthy",
"metrics": {
Expand All @@ -213,20 +238,19 @@ The status endpoint has two routes:
}
}
```

- `/<statusEndpointsRoot>/pubkey`
- `/status/pubkey`
Returns the public key of the node.
```json
```jsonc
{
"pubkey": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f"
}
```

### Configuration
#### Status Configuration

The status endpoints can be configured in the config file:
The status endpoints can be configured in the config file under the statusEndpoints attribute:

```json
```jsonc
{
// Other config...
"statusEndpoints": {
Expand Down Expand Up @@ -329,7 +353,7 @@ Basic Helm configuration example:
# ... other configuration ...

secret:
sedaDataProxyPrivateKey: "" # Will be set via CLI
sedaDataProxyPrivateKey: "" # Will be set via CLI

# Remove this flag in production - it disables request verification
sedaProxyFlags: "--disable-proof"
Expand All @@ -349,4 +373,4 @@ helm install my-proxy ./helm --set secret.sedaDataProxyPrivateKey=$SEDA_DATA_PRO
```

> [!NOTE]
> The above is a minimal example. Your specific deployment may require additional configuration for services, ingress, resources, and security settings based on your infrastructure requirements. Please consult with your infrastructure team for production deployments.
> The above is a minimal example. Your specific deployment may require additional configuration for services, ingress, resources, and security settings based on your infrastructure requirements. Please consult with your infrastructure team for production deployments.

0 comments on commit 1a5a0ba

Please sign in to comment.