Shares

This guide explains how to manage Shares and view share-level metrics.

Why this matters

• A Share exposes a backend (HTTP/TCP) through a Frontdoor. It defines routing and security context.
• Shares transition through states like PROVISIONING and ACTIVE; plan for eventual consistency after create/delete.
• Use metrics to validate performance and quickly detect regressions per Share.

Assumptions

• The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
• Expected headers for all API calls:

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Operations

List shares

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/shares?page=0&size=20"

Response example

{
  "content": [
    {
      "zId": "2jXRXXtSZn6Z8DfDhHxLZC",
      "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
      "authProviderId": null,
      "frontendId": "dKRfL_UMa8DAP7KmYOdOr",
      "name": "publicdemo",
      "shareMode": "public",
      "backendMode": "proxy",
      "envZId": "ijcrWb-ZOq",
      "frontendSelection": "public",
      "frontendEndpoint": "http://backend.svc.cluster.local:8080",
      "backendProxyEndpoint": "https://splash.tools.netfundry.io",
      "oauthProvider": null,
      "oauthEmailDomains": null,
      "oauthAuthorizationCheckInterval": null,
      "reserved": true,
      "limited": false
    }
  ]
}

Get a share

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/shares/shr-1

Response example

{
  "zId": "2jXRXXtSZn6Z8DfDhHxLZC",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "authProviderId": null,
  "frontendId": "bMTHPrtQ",
  "name": "publicdemo",
  "shareMode": "public",
  "backendMode": "proxy",
  "envZId": "ijcrWb-ZOq",
  "frontendSelection": "public",
  "frontendEndpoint": "http://backend.svc.cluster.local:8080",
  "backendProxyEndpoint": "https://splash.tools.netfundry.io",
  "oauthProvider": null,
  "oauthEmailDomains": null,
  "oauthAuthorizationCheckInterval": null,
  "reserved": true,
  "limited": false
}

Create a share

A Share is what maps a host and optional path on your chosen Frontend to the internal URL your service listens on. The frontendIds are from listing the Frontends.

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "publicdemo",
        "frontendIds": [
          "bMTHPrtQ"
        ],
        "target": "http://backend.svc.cluster.local:8080"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/shares

Response example

{
  "zId": "2jXRXXtSZn6Z8DfDhHxLZC",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "authProviderId": null,
  "frontendId": "bMTHPrtQ",
  "name": "publicdemo",
  "shareMode": "public",
  "backendMode": "proxy",
  "envZId": "ijcrWb-ZOq",
  "frontendSelection": "public",
  "frontendEndpoint": "http://backend.svc.cluster.local:8080",
  "backendProxyEndpoint": "https://splash.tools.netfundry.io",
  "oauthProvider": null,
  "oauthEmailDomains": null,
  "oauthAuthorizationCheckInterval": null,
  "reserved": true,
  "limited": false
}

Delete a share

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/shares/shr-1

The delete request has an empty response.

Technical Notes

Metrics

All shares track data metrics, see Metrics for more information.

Paths

- GET /frontdoor/\{frontdoorId\}/shares[?page=0&size=20]
- GET /frontdoor/\{frontdoorId\}/shares/{id}
- POST /frontdoor/\{frontdoorId\}/shares
- DELETE /frontdoor/\{frontdoorId\}/shares/{id}
- GET /frontdoor/\{frontdoorId\}/shares/{id}/metrics?range=PT1H
- GET /frontdoor/\{frontdoorId\}/metrics?range=PT1H

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.