NetFoundry Public REST API API Reference

NetFoundry’s web console and API are used to define networks by designing and instantly deploying AppWANs which are policies that describe how endpoints are permitted to access services.

Most operations require an expiring auth token as described in the authentication guide.

You may find more helpful guides, references, and tools to use with this API in the NetFoundry Developer Portal.

Version: 0.0.3-SNAPSHOT

azureSubscriptions

list Azure subscriptions

GET /azureSubscriptions

Returns a list of stored Azure subscriptions in your account.

200 OK

200

store Azure subscription details

POST /azureSubscriptions

Store an Azure subscriptionID, tenant ID (AD), and Application ID and key for use with Azure Virtual WAN. The application must have permission to create a Virtual WAN (branch) site in your subscription.

200 OK

200

fetch the attributes of a subscription

GET /azureSubscriptions/{azureSubscriptionId}

Returns the object describing one stored Azure subscription i.e. subscription ID, tenant ID, and application client ID (not the key).

azureSubscriptionId: object
in path

the id of the subscription

200 OK

200

redefine an Azure subscription

PUT /azureSubscriptions/{azureSubscriptionId}

Accepts the same parameters as the operation that stored the subscription. Send all attributes, not only those that have changed.

azureSubscriptionId: object
in path

the id of the subscription

202 Accepted

202

delete stored Azure subscription details

DELETE /azureSubscriptions/{azureSubscriptionId}

delete stored Azure subscription details

azureSubscriptionId: object
in path

the id of the subscription

202 Accepted

202

list Azure vWAN sites for subscription

GET /azureSubscriptions/{azureSubscriptionId}/virtualWanSites

Returns a list of Azure Virtual WAN sites that were created by a stored suscription credential set.

azureSubscriptionId: object
in path

the id of the subscription

200 OK

200

describe a vWAN branch site

POST /azureSubscriptions/{azureSubscriptionId}/virtualWanSites

Define an Azure Virtual WAN branch site. A "site" here is a special type of NetFoundry endpoint with metadata describing the IP routes to be attached to your Azure Virtual WAN.

azureSubscriptionId: object
in path

the id of the subscription

200 OK

200

delete Azure vWAN site

DELETE /azureSubscriptions/{azureSubscriptionId}/virtualWanSites/{siteId}

delete Azure vWAN site

azureSubscriptionId: object
in path

the id of the subscription

siteId: object
in path

the id of the Azure vWAN VPN site

202 Accepted

202

dataCenters

fetch data center(s)

GET /dataCenters

Returns a list of all data centers or the attributes of one datacenter matching query ?locationCode={locationCode}. A data center is a compute location and is associated with one or more geographic regions in /rest/v1/geoRegions.

locationCode: object
in query

the locationCode by which to filter data centers

200 OK

200

fetch a data center by ID

GET /dataCenters/{dataCenterId}

Fetch the attributes of a single data center by ID.

dataCenterId: object
in path

the id of the data center

200 OK

200

elastic

query Elasticsearch about your network

POST /elastic/ncentityevent/{orgId}/_search/

Proxy a query to Elasticsearch. Know more about this interface by reading this blog post.

orgId: object
in path

the id of the network group

200 OK

200

geoRegions

list all georegions

GET /geoRegions

Returns a list of geographic regions. These are longitudinal regions comprising provider-specific datacenters.

200 OK

200

fetch a georegion

GET /geoRegions/{geoRegionId}

Fetch the attributes of a geographic region by ID

geoRegionId: object
in path

the id of the geographic region

200 OK

200

hosts

list hosts for network

GET /hosts

Returns a list of hosts for a network.

200 OK

200

fetch a host

GET /hosts/{hostId}

Fetch the attributes of a host by ID.

hostId: object
in path

(no description)

200 OK

200

network-processes

list processes for network

GET /network-processes

List running processes for a network.

200 OK

200

fetch network processes by key

GET /network-processes/{businessKey}

Fetch network process statuses for a business key.

businessKey: object
in path

the business key to filter

200 OK

200

networkConfigMetadata

list network configurations

GET /networkConfigMetadata

Returns a list of network configuration templates.

200 OK

200

add a network configuration

POST /networkConfigMetadata

Store a new network configuration template.

202 Accepted

202

fetch a network configuration

GET /networkConfigMetadata/{networkConfigMetadataId}

Fetch the attributes of a network configuration template by ID.

networkConfigMetadataId: object
in path

the id of the configuration

200 OK

200

redefine a network configuration

PUT /networkConfigMetadata/{networkConfigMetadataId}

Redefine an existing network configuration template.

networkConfigMetadataId: object
in path

(no description)

202 Accepted

202

delete a network configuration

DELETE /networkConfigMetadata/{networkConfigMetadataId}

Remove a network configuration template.

networkConfigMetadataId: object
in path

the id of the configuration

202 Accepted

202

networkgroups

List all endpoints for network group.

GET /networkgroups/{networkGroupId}/endpoints

List all endpoints for network group.

networkGroupId: object
in path

the ID of the network group for which to get endpoints

200 OK

200

list services for network group

GET /networkgroups/{networkGroupId}/services

Returns a list of all of the services in networks that are in a network group.

networkGroupId: object
in path

the id of the network group

200 OK

200

networks

list all networks for network group

GET /networks

Returns a list of networks in a network group. Pagination params:

  • page: page number
  • size: number of list elements per page
  • sort: comma-separated list of sort field (an attribute of the networks) and direction ("ASC" or "DESC")

Produces a top-level map .page in the response like

"page": {
    "number": 1,
    "size": 1,
    "totalElements": 1,
    "totalPages": 1
}
200 OK

200

create a network

POST /networks

Create a network. The only required parameter is name, and other params are not typically beneficial.

202 Accepted

202

fetch a network

GET /networks/{networkId}

Fetch the attributes of a network by ID

networkId: object
in path

the id of the network

200 OK

200

redefine a network

PUT /networks/{networkId}

Redefine an existing network by resending all attributes.

networkId: object
in path

the id of the network

200 OK

200

destroy a network

DELETE /networks/{networkId}

Permanently destroy all resources associated with a network.

networkId: object
in path

the id of the network

202 Accepted

202

list keys of AppWAN processes

GET /networks/{networkId}/appWan-processes

Monitor the progress of an AppWAN modification by listing business keys and then inspecting them with get-processes-for-appwan.

networkId: object
in path

the id of the network

200 OK

200

list AppWANs for network

GET /networks/{networkId}/appWans

Returns a list of AppWANs for a network.

Pagination params:

  • page: page number
  • size: number of list elements per page
  • sort: comma-separated list of sort field (an attribute of the AppWANs) and direction ("ASC" or "DESC")

Produces a top-level map .page in the response like

"page": {
    "number": 1,
    "size": 1,
    "totalElements": 1,
    "totalPages": 1
}
networkId: object
in path

the id of the network

200 OK

200

Initialize an empty AppWAN

POST /networks/{networkId}/appWans

Initialize an empty AppWAN for authorizations that will be added later.

networkId: object
in path

the id of the network

202 Accepted

202

download a network blueprint

GET /networks/{networkId}/blueprint

Download the as-code YAML blueprint of a network.

network: name: Network12 productFamily: DVN productVersion: 1.0.0-123 gateways: [] clients: [] endpointGroups: [] services: [] appWans: [] gatewayClusters: []

networkId: object
in path

the id of the network

200 OK

200

create a CA

POST /networks/{networkId}/cas

Create a certificate authority for this network.

networkId: object
in path

the id of the network

201 Created

201

list endpoint groups

GET /networks/{networkId}/endpointGroups

Returns a list of endpoint groups in a network.

networkId: object
in path

the id of the network

200 OK

200

create an endpoint group

POST /networks/{networkId}/endpointGroups

Create a group of endpoints. This allows some endpoints to be added together to an AppWAN.

networkId: object
in path

the id of the network

201 Created

201

List of all endpoints for network.

GET /networks/{networkId}/endpoints

Pagination params:

  • page: page number
  • size: number of list elements per page
  • sort: comma-separated list of sort field (an attribute of the endpoints) and direction ("ASC" or "DESC") Produces a top-level map .page in the response like
    "page": {
     "number": 1,
     "size": 1,
     "totalElements": 1,
     "totalPages": 1
    }
    
networkId: object
in path

the ID of the network to get paginated endpoints from

200 OK

200

Create a node(s) on the edge of your network.

POST /networks/{networkId}/endpoints

An endpoint is a node on the edge of your network. Protected network traffic flows to, from, and through endpoints. Clients and gateways are initiating endpoints from which traffic flows toward services. Services are terminated by an endpoint to which traffic flows from clients and gateways. An endpoint in an AppWAN may represent an app, a device, or some IP addresses. For example,

  • An app that is built with a Ziti Endpoint SDK is an embedded endpoint, and
  • a device where Tunneler is running is a client endpoint, and
  • a router where Tunneler is running is a gateway endpoint forwarding for some IP addresses.

See the schema here for possible values for the fields. The most commonly-used fields are name, endpointType, geoRegionId.

It is also possible to upload a CSV file to this endpoint. Headings are:

  • NAME: a required, meaningful string that is unique within this network
  • ENDPOINTTYPE: required all-caps string without whitespace e.g. "VCPEGW". All possible values described in the schema for create-endpoint
  • GEOREGION: optional but preferred location field. The display name of the geographic region i.e. attribute name from /rest/v1/geoRegions.
  • DATACENTER: This optional and alterative to the preferred location field: GEOREGION. The display name of the specific datacenter in a georegion i.e. attribute locationName from /rest/v1/dataCenters.
  • PROVIDER: optional value specifying dataCenter cloud provider from /rest/v1/dataCenters attribute provider.
networkId: object
in path

the ID of the network

202 Accepted

202

list HA clusters

GET /networks/{networkId}/gatewayClusters

Returns a list of HA clusters for a network. An HA cluster is a pair of gateway endpoints which cooperatively terminate a service.

networkId: object
in path

the id of the network

200 OK

200

create an HA cluster

POST /networks/{networkId}/gatewayClusters

Create a high-availability pair of gateway endpoints. A gateway cluster provides fault tolerant termination for the services it provides to an AppWAN.

networkId: object
in path

the id of the network

202 Accepted

202

fetch the config for a network

GET /networks/{networkId}/networkConfigMetadata

Fetch the attributes of the configuration for a network. Stored network configuration templates are used to size a network's resources appropriately.

networkId: object
in path

the id of the network

200 OK

200

fetch controller host details for a network

GET /networks/{networkId}/networkControllerHosts

Fetch attributes of the host where the dedicated network controller instance is running.

networkId: object
in path

the id of the network

200 OK

200

list service groups

GET /networks/{networkId}/serviceGroups

Returns a list of service groups for a network.

networkId: object
in path

the id of the network

200 OK

200

list services for a network

GET /networks/{networkId}/services

Returns a list of all of the services that are part of this network.

Optional Pagination parameters:

  • page: page number
  • size: number of list elements per page
  • sort: comma-separated list of sort field (an attribute of the services) and direction ("ASC" or "DESC") Produces a top-level map .page in the response like
    "page": {
     "number": 1,
     "size": 1,
     "totalElements": 1,
     "totalPages": 1
    }
    
networkId: object
in path

the id of the network

page: object
in query

the page number to return

size: object
in query

the number of results per page

sort: object
in query

comma-separated string with two fields: the attribute on which to key, and sort order as "asc" (ascending) or "des"

200 OK

200

create a service definition

POST /networks/{networkId}/services

Use this operation to describe the path to a server resource. A service is typically in one of three main classes:

  • CS: client service, this is the most common and describes a range of ports on one IP over TCP or UDP or both
  • GW: gateway service, describes a range of ports on a range of IPs over TCP or UDP or both
  • ICMP: handles ICMP traffic instead of TCP or UDP

When creating any of these types of services, either endpointId (the terminating endpoint) or gatewayClusterId (for high availability) needs to be supplied.

Service(s) may also be created by uploading a CSV file to this API endpoint with headings * NAME: required meaningful name of the service

  • STATUS: ignored
  • TYPE: required service class e.g. "IP Host" or "Network"
  • PROTOCOLSTRING: required TCP, UDP, ALL (meaning both TCP and UDP), or ICMP
  • IPADDRESSSTRING: required dotted-quad or CIDR describing the server resource
  • INTERCEPTADDRESS: optional fictitious dotted-quad or CIDR to masquerade as the server resource
  • PORTRANGE: required port or hypenated range of TCP or UDP ports
  • ENDPOINT: required name of the terminating endpoint from endpoint attribute name
networkId: object
in path

the id of the network

202 Accepted

202

list transfer node pools for network

GET /networks/{networkId}/transferNodePools

Returns a list of transfer node pools for the network.

networkId: object
in path

the id of the network

200 OK

200

inspect an AppWAN process for key

GET /networks/{networkId}/appWan-processes/{businessKey}

Use this to inspect a process discovered with find-appwan-processes. Returns an array of processing steps that an AppWan update process will traverse. The returned steps contain a current status (in progress, completed, etc...), reflecting the current state of that process-step.

networkId: object
in path

the id of the network

businessKey: object
in path

the business key

200 OK

200

fetch an AppWAN

GET /networks/{networkId}/appWans/{appWanId}

Fetches the attributes of a single AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

redefine an AppWAN

PUT /networks/{networkId}/appWans/{appWanId}

Redefine an existing AppWAN by resending all attributes.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

Destroy an AppWAN

DELETE /networks/{networkId}/appWans/{appWanId}

Permanently destroy an AppWAN and therefore deauthorize all of the contained endpoint-to-service associations.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

list CAs for network

GET /networks/{networkId}/cas/

Returns a list of all certificate authorities for a network.

networkId: object
in path

the id of the network

200 OK

200

fetch a CA

GET /networks/{networkId}/cas/{caId}

Fetch the attributes of a single certificate authority.

networkId: object
in path

the id of the network

caId: object
in path

the id of the certificate authority

200 OK

200

redefine a CA

PUT /networks/{networkId}/cas/{caId}

Redefine a certificate authority by re-sending all attributes.

networkId: object
in path

the id of the network

caId: object
in path

the id of the certificate authority

201 Created

201

delete a CA

DELETE /networks/{networkId}/cas/{caId}

Delete a certificate authority from this network.

networkId: object
in path

the id of the network

caId: object
in path

the id of the certificate authority

200 OK

200

fetch an endpoint group

GET /networks/{networkId}/endpointGroups/{endpointGroupId}

Fetch the attributes of an endpoint group by ID.

networkId: object
in path

the id of the network

endpointGroupId: object
in path

the id of the endpoint group

200 OK

200

redefine an endpoint group

PUT /networks/{networkId}/endpointGroups/{endpointGroupId}

Redefine an endpoint group by resending all attributes.

networkId: object
in path

the id of the network

endpointGroupId: object
in path

the id of the endpoint group

200 OK

200

delete an endpoint group

DELETE /networks/{networkId}/endpointGroups/{endpointGroupId}

Permanently destroy a group. The endpoints in the group are not deleted.

networkId: object
in path

the id of the network

endpointGroupId: object
in path

the id of the endpoint group

202 Accepted

202

fetch the object describing one endpoint (not a list)

GET /networks/{networkId}/endpoints/{endpointId}

fetch the object describing one endpoint (not a list)

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint

200 OK

200

Modify an endpoint's attributes

PUT /networks/{networkId}/endpoints/{endpointId}

Modify an endpoint's attributes

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint

202 Accepted

202

Destroy an endpoint

DELETE /networks/{networkId}/endpoints/{endpointId}

Destroy an endpoint

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint to delete

202 Accepted

202

fetch an HA cluster

GET /networks/{networkId}/gatewayClusters/{gatewayClusterId}

Fetch the attributes of an HA cluster by ID.

networkId: object
in path

the id of the network

gatewayClusterId: object
in path

the id of the gateway cluster

200 OK

200

redefine an HA cluster

PUT /networks/{networkId}/gatewayClusters/{gatewayClusterId}

Redefine an HA cluster by resending all attributes.

networkId: object
in path

the id of the network

gatewayClusterId: object
in path

the id of the gateway cluster

202 Accepted

202

delete an HA cluster

DELETE /networks/{networkId}/gatewayClusters/{gatewayClusterId}

Permanently destroy an HA cluster. This removes the logical grouping of the gateway endpoints that compose an HA cluster, but does not delete the endpoints themselves.

networkId: object
in path

the id of the network

gatewayClusterId: object
in path

the id of the gateway cluster

202 Accepted

202

fetch a service group

GET /networks/{networkId}/serviceGroups/{serviceGroupId}

Fetch the attributes of a service group by ID.

networkId: object
in path

the id of the network

serviceGroupId: object
in path

the id of the service group

200 OK

200

fetch the attributes of a service

GET /networks/{networkId}/services/{serviceId}

Returns the object describing a particular service.

networkId: object
in path

the id of the network

serviceId: object
in path

the id of the service

200 OK

200

redefine a server resource

PUT /networks/{networkId}/services/{serviceId}

Updates a service definition using the same parameters used to initially define the service. The request should contain a full Service object.

networkId: object
in path

the id of the network

serviceId: object
in path

the id of the service

202 Accepted

202

destroy a service definition

DELETE /networks/{networkId}/services/{serviceId}

Undefine a service for this specific network.

networkId: object
in path

the id of the network

serviceId: object
in path

the id of the service

202 Accepted

202

fetch a transfer node pool

GET /networks/{networkId}/transferNodePools/{transferNodePoolId}

Fetch the attributes of a single transfer node pool.

networkId: object
in path

the id of the network

transferNodePoolId: object
in path

the id of the transfer node pool

200 OK

200

download AppWAN YAML

GET /networks/{networkId}/appWans/{appWanId}/blueprint

Download the as-code YAML definition of an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

list endpoint groups for AppWAN

GET /networks/{networkId}/appWans/{appWanId}/endpointGroups

Returns a list of endpoint groups in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

Authorize an endpoint group

POST /networks/{networkId}/appWans/{appWanId}/endpointGroups

Authorize a group of endpoints to initiate connections to all services in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

Remove one or more endpoint groups from an AppWAN

DELETE /networks/{networkId}/appWans/{appWanId}/endpointGroups

Deauthorize one or more endpoint groups (groups of clients and gateways) for all services in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

list endpoints for an AppWAN

GET /networks/{networkId}/appWans/{appWanId}/endpoints

Returns a list of endpoints in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

Authorize one or more endpoints

POST /networks/{networkId}/appWans/{appWanId}/endpoints

Authorize one or more endpoints, which are "clients" or "gateways", to initiate connections to any service in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

Remove one or more endpoints from an AppWAN

DELETE /networks/{networkId}/appWans/{appWanId}/endpoints

Deauthorize one or more endpoints (clients and gateways) for all services in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

list services for AppWAN

GET /networks/{networkId}/appWans/{appWanId}/services

Returns a list of services in an AppWAN.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

200 OK

200

Authorize one or more services

POST /networks/{networkId}/appWans/{appWanId}/services

Authorize all endpoints in an AppWAN to initiate connections to one or more services additional services.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

Deauthorize one or more services

DELETE /networks/{networkId}/appWans/{appWanId}/services

Deauthorize all endpoints in an AppWAN for one or more services.

networkId: object
in path

the id of the network

appWanId: object
in path

the id of the AppWAN

202 Accepted

202

fetch CA certificate

POST /networks/{networkId}/cas/{caId}/verify

Fetch the certificate authority's issuer certificate.

networkId: object
in path

the id of the network

caId: object
in path

the id of the certificate authority

200 OK

200

add endpoints to group

POST /networks/{networkId}/endpointGroups/{endpointGroupId}/endpoints

Add client or gateway endpoints to a group. Groups may be added to an AppWAN.

networkId: object
in path

the id of the network

endpointGroupId: object
in path

the id of the endpoint group

202 Accepted

202

remove endpoints from group

DELETE /networks/{networkId}/endpointGroups/{endpointGroupId}/endpoints

Remove endpoints from a group. Removed endpoints will lose access to AppWANs to which the group was added.

networkId: object
in path

the id of the network

endpointGroupId: object
in path

the id of the endpoint group

202 Accepted

202

Array of appWans associated with an Endpoint

GET /networks/{networkId}/endpoints/{endpointId}/appWans

Array of appWans associated with an Endpoint

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint

200 OK

200

Array of endpointGroups associated with an Endpoint

GET /networks/{networkId}/endpoints/{endpointId}/endpointGroups

Array of endpointGroups associated with an Endpoint

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint

200 OK

200

Array of services associated with an Endpoint

GET /networks/{networkId}/endpoints/{endpointId}/services

Array of services associated with an Endpoint

networkId: object
in path

the ID of the network

endpointId: object
in path

the ID of the endpoint

200 OK

200

list endpoints in HA cluster

GET /networks/{networkId}/gatewayClusters/{gatewayClusterId}/endpoints

Returns a list of endpoints in an HA cluster.

networkId: object
in path

the id of the network

gatewayClusterId: object
in path

the id of the gateway cluster

200 OK

200

list services for an HA cluster

GET /networks/{networkId}/gatewayClusters/{gatewayClusterId}/services

Returns a list of services terminated by an HA cluster.

networkId: object
in path

the id of the network

gatewayClusterId: object
in path

the id of the gateway cluster

200 OK

200

list associated AppWANs

GET /networks/{networkId}/services/{serviceId}/appWans

Returns a list of all the AppWANs of which this service is a member.

networkId: object
in path

the id of the network

serviceId: object
in path

the id of the service

200 OK

200

organizations

fetch an organization

GET /organizations/{organizationId}

Fetch the attributes of an organization by ID.

organizationId: object
in path

the id of the network group (formerly "organization")

200 OK

200

redefine an organization

PUT /organizations/{organizationId}

Redefine an organization by resending all attributes.

organizationId: object
in path

the id of the network group (formerly "organization")

202 Accepted

202

fetch organization for a billing account

GET /organizations/billing-accounts/{billingAccountId}

Fetch the attributes of the organization associated with a billing account ID.

billingAccountId: object
in path

the id of the billing account

200 OK

200

create network from blueprint

POST /organizations/{organizationId}/networks

Create a network by uploading a YAML blueprint. You may download a blueprint for an existing network with GET /rest/v1/networks/{networkId}}/blueprint.

organizationId: object
in path

the id of the network group (formerly "organization")

202 Accepted

202

workflow-status

list workflow statuses

GET /workflow-status

List asynchronous workflow process statuses.

200 OK

200

check the status of a process

GET /workflow-status/{businessKey}

Fetch the status of a workflow process by business key.

businessKey: object
in path

the business key

200 OK

200