Upstreams
Upstreams are a core part of SaaS Custom Domains.
An upstream refers to the server to which the reverse proxy forwards requests. In your case, this is most likely your web application, e.g. app.mydomain.com.
On this page, we'll dive into the different upstream endpoints you can use to manage upstreams programmatically. We'll look at how to query, create, update, and delete upstreams.
The upstream model
The upstream model contains all the information about your upstreams, such as their unique identifier, hostname, port, if upstream is expecting TLS traffic, if it is a Bubble.io app etc.
Properties
- Name
uuid- Type
- string
- Description
Unique identifier for the upstream.
- Name
host- Type
- string
- Description
The host of the upstream. This is the host of your web application where you expect to receive requests, e.g.
app.mysaas.com.
- Name
port- Type
- integer
- Description
The port of the upstream. This is the port on which your web application listens. Default value is
443.
- Name
tls- Type
- boolean
- Description
Whether the upstream is using TLS. Default value is
true.
- Name
created_at- Type
- timestamp
- Description
The date and time when the upstream was created.
- Name
updated_at- Type
- timestamp
- Description
The date and time when the upstream was last updated.
- Name
bubble_io- Type
- boolean
- Description
Whether the upstream is a Bubble.io app. Default value is
false.
List all upstreams for an account
This endpoint allows you to retrieve a paginated list of all your upstreams. By default, 20 upstreams are shown per page.
Optional attributes
- Name
host- Type
- string
- Description
Find upstream with the given host.
- Name
page- Type
- integer
- Description
The page number to retrieve. Default value is
1.
- Name
per_page- Type
- integer
- Description
The number of items to retrieve per page. Default value is
20.
Request
curl -G https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams \
-H "Authorization: Bearer {token}" \
-d page=7
Response
{
"pagination": {
"page": 7,
"count": 237
},
"records": [
{
"uuid": "upstream_1234567890",
"host": "app.myapp.com",
"port": 443,
"tls": true,
"created_at": "2023-03-10T07:14:35.823-06:00",
"updated_at": "2023-03-10T07:14:35.823-06:00"
},
{
"uuid": "upstream_0987654321",
// ...
}
]
}
Create an upstream
This endpoint allows you to add a new upstream. To add an upstream, you must provide at least provide upstream's host.
Required attributes
- Name
host- Type
- string
- Description
The host of the upstream. This is the host of your web application where you expect to receive requests, e.g.
app.mysaas.com.
Optional attributes
- Name
tls- Type
- boolean
- Description
Whether the upstream is using TLS. Default value is
true.
- Name
port- Type
- integer
- Description
The port of the upstream. This is the port on which your web application listens. Default value is
443.
- Name
bubble_io- Type
- boolean
- Description
Whether the upstream is a Bubble.io app. Default value is
false.
Request
curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams \
-H "Authorization: Bearer {token}" \
-d host="app.mysaas.com" \
-d port=8888
Response
{
"uuid":"upstream_180e8083",
"host":"app.mysaas.com",
"port":8888,
"tls":true,
"bubble_io":false,
"created_at":"2023-03-10T14:05:32.580+00:00",
"updated_at":"2023-03-10T14:05:32.580+00:00",
}
Retrieve an upstream
This endpoint allows you to retrieve an upstream by providing its UUID. Refer to the list at the top of this page to see which properties are included with upstream objects.
Request
curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid \
-H "Authorization: Bearer {token}"
Response
{
"uuid":"upstream_180e8083",
"host":"app.mysaas.com",
"port":8888,
"tls":true,
"bubble_io":false,
"created_at":"2023-03-10T14:05:32.580+00:00",
"updated_at":"2023-03-10T14:05:32.580+00:00",
}
Delete an upstream
This endpoint allows you to delete upstreams. Note: This will also delete custom domains for that upstream.
Request
curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid \
-H "Authorization: Bearer {token}"
Response
{
"message": "Upstream upstream_180e8083 (app.mysaas.com) deleted."
}