Network Control API documentation version v1.1

http://api.example.com/x-nmos/netctrl/{version}

  • version: required(v1.1)

Overview

The Network Control API is exposed by an NMOS network controller. It provides APIs to create and manage network flows, add senders and receivers for the flows, and fetch network details.

Further Documentation

Further normative documentation covering the behaviour of this API is contained in the docs folder of this repository.

Base

get

get

List the resources that can be accessed from the base URL

List the resources that can be accessed from the base URL

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Network Control API base resource",
  "title": "Network Control API base resource",
  "items": {
    "type": "string",
    "enum": [
      "network-devices/",
      "endpoints/",
      "network-links/",
      "network-flows/",
      "network-address-translations/"
    ]
  },
  "minItems": 5,
  "maxItems": 5,
  "uniqueItems": true
}

Example:

[
  "network-devices/",
  "endpoints/",
  "network-links/",
  "network-flows/"
]

Network Devices

get

get

List Network Devices. NB: Query parameters should be implemented for all permitted resource attributes.

get

get

Get a single Network Device

Get a single Network Device

URI Parameters

  • networkDeviceId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Device.

    Example:

    3f383f86-c977-498f-81bf-04c5cb8a0e0d

HTTP status code 200

Body

Media type: application/json

Type: NetworkDevice

Example:

{
  "id": "11b8973e-91c9-462d-8dad-6b37e53b3b9f",
  "chassis_id": "95-a6-37-bb-b2-61",
  "mgmt_ip": "10.10.10.16",
  "mtu": 1500,
  "interfaces": [
    {
      "port_id": "Ethernet 1/1",
      "admin_status": "up",
      "oper_status": "up",
      "speed": "1Gbit/s",
      "mtu": 1500
    },
    {
      "port_id": "Ethernet 1/2",
      "admin_status": "up",
      "oper_status": "up",
      "speed": "100Gbit/s"
    },
    {
      "port_id": "Ethernet 1/3",
      "admin_status": "up",
      "oper_status": "up",
      "speed": "100Gbit/s"
    }
  ],
  "label": "Network spine"
}

HTTP status code 404

Returned when the Network Device ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Endpoints

get

get

List Endpoints. NB: Query parameters should be implemented for all permitted resource attributes.

options get put patch delete

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

get

Get a single Endpoint

put

Register a new Endpoint. The PUT is invoked to inform the network controller about the presence of an Endpoint. The Endpoint should include details of the Network Device the Endpoint is attached to. The attached network device details can be fetched by the endpoint through LLDP (if the endpoint is LLDP capable) or manual entry in the caller of this API (e.g., a broadcast controller). The network controller may verify these details. If the details are invalid, the network controller may reject the request. When the attached network device details are not included in the request, the network controller may attempt to determine them and include them in the registered Endpoint. However, if the network controller cannot determine them, it may reject the the request. Subsequent PUT requests should receive an error response. Updates should be done using PATCH.

patch

Update an existing Endpoint's attributes.

delete

Delete an existing Endpoint.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • endpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

HTTP status code 200

HTTP status code 403

Get a single Endpoint

URI Parameters

  • endpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

HTTP status code 200

Body

Media type: application/json

Type: Endpoint

Example:

{
  "id": "d9c88a0a-c0c8-4ec8-ade5-fde9106e5040",
  "chassis_id":"1e-a1-79-16-0a-6b",
  "port_id": "bf-f8-01-60-49-bc",
  "ip_address": "10.10.34.24",
  "attached_network_device": {
    "chassis_id": "7a-c9-d7-f0-e2-03",
    "port_id": "Ethernet 2/2"
  },
  "max_bandwidth": "10Gbit/s",
  "role": "sender",
  "label": "Video transmitter gateway endpoint."
}

HTTP status code 404

Returned when the requested Endpoint ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Register a new Endpoint. The PUT is invoked to inform the network controller about the presence of an Endpoint. The Endpoint should include details of the Network Device the Endpoint is attached to. The attached network device details can be fetched by the endpoint through LLDP (if the endpoint is LLDP capable) or manual entry in the caller of this API (e.g., a broadcast controller). The network controller may verify these details. If the details are invalid, the network controller may reject the request. When the attached network device details are not included in the request, the network controller may attempt to determine them and include them in the registered Endpoint. However, if the network controller cannot determine them, it may reject the the request. Subsequent PUT requests should receive an error response. Updates should be done using PATCH.

URI Parameters

  • endpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

Body

Media type: application/json

Type: Endpoint

Example:

{
  "id": "dc7c36a5-cd6d-44bb-a1ac-6e328c018de0",
  "chassis_id":"91-0c-41-81-fb-40",
  "port_id": "d6-f2-fa-ae-29-78",
  "ip_address": "10.10.26.24",
  "attached_network_device": {
    "chassis_id": "d7-28-68-a3-89-4f",
    "port_id": "Ethernet 1/2"
  },
  "max_bandwidth": "40Gbit/s",
  "role": "receiver",
  "label": "Video receiver gateway endpoint."
}

HTTP status code 201

Returned when the Endpoint is registered with the network controller successfully. The Location header should indicate the location of the created resource.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/{version}/endpoints/d0729fa2-83ba-4e6b-8817-d48a4bf28f74

Body

Media type: application/json

Type: Endpoint

Example:

{
  "id": "d9c88a0a-c0c8-4ec8-ade5-fde9106e5040",
  "chassis_id":"1e-a1-79-16-0a-6b",
  "port_id": "bf-f8-01-60-49-bc",
  "ip_address": "10.10.34.24",
  "attached_network_device": {
    "chassis_id": "7a-c9-d7-f0-e2-03",
    "port_id": "Ethernet 2/2"
  },
  "max_bandwidth": "10Gbit/s",
  "role": "sender",
  "label": "Video transmitter gateway endpoint."
}

HTTP status code 400

Returned when the PUT request is incorrectly formatted or has missing mandatory attributes or an attribute is invalid given the API's configuration, such as when the Endpoint ID already exists, or the network controller can identify that the details for other parameters do not agree with the information held by the network device. Error responses should contain a relevant message.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 409

Returned when the PUT request is invalid because an Endpoint with the same unique details (Chassis ID, Port ID and IP Address) already exists. The existing Endpoint is indicated via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/{version}/endpoints/b2ff7bc0-de0c-478a-bd93-4be0b13a2ffe

Body

Media type: application/json

Type: ErrorSchema

Update an existing Endpoint's attributes.

URI Parameters

  • endpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Patch request schema for updating an existing endpoint.",
  "title": "Schema to modify an endpoint with new values.",
  "properties": {
    "ip_address": {
      "type": "string",
      "description": "IP address on which the endpoint sends/receives flows. IP address must be unique in the network.",
      "anyOf": [
        {
          "format": "ipv4"
        },
        {
          "format": "ipv6"
        }
      ]
    },
    "attached_network_device": {
      "type": "object",
      "description": "Peer network device (switch) details. This cannot be an endpoint.",
      "required": [
        "chassis_id",
        "port_id"
      ],
      "properties": {
        "chassis_id": {
          "description": "Matches the chassis_id of the peer network device. Where LLDP is implemented on the network device interfaces, the LLDP Chassis ID should match this value.",
          "anyOf": [
            {
              "type": "string",
              "pattern": "^([0-9a-f]{2}-){5}([0-9a-f]{2})$",
              "description": "When the Chassis ID is a MAC address, use this format."
            },
            {
              "type": "string",
              "pattern": "^.+$",
              "description": "When the Chassis ID is anything other than a MAC address, a freeform string may be used."
            }
          ]
        },
        "port_id": {
          "description": "Matches the port_id of the interface on the peer network device to which the endpoint is connected. Where LLDP is implemented on the network device interfaces, the LLDP Port ID should match this value.",
          "anyOf": [
            {
              "type": "string",
              "pattern": "^([0-9a-f]{2}-){5}([0-9a-f]{2})$",
              "description": "When the Chassis ID is a MAC address, use this format."
            },
            {
              "type": "string",
              "pattern": "^.+$",
              "description": "When the Chassis ID is anything other than a MAC address, a freeform string may be used."
            }
          ]
        }
      }
    },
    "max_bandwidth": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?[kMG]bit\\/s$",
      "description": "Maximum bandwidth that the sender is allowed to send, formatted as a number followed by kbit/s, Mbit/s, Gbit/s. NB: Values should be formatted with no fraction component if possible, using the largest unit that allows that."
    },
    "role": {
      "description": "The role of the endpoint as a sender or receiver.",
      "type": "string",
      "enum": [
        "sender",
        "receiver",
        "both"
      ]
    },
    "label": {
      "description": "Freeform string label for the endpoint",
      "type": "string"
    }
  }
}

Example:

{
  "ip_address": "10.18.34.24",
  "max_bandwidth": "10Gbit/s",
  "role": "both"
}

HTTP status code 200

Returned when the Endpoint is updated successfully. The updated Endpoint is returned in the response.

Body

Media type: application/json

Type: Endpoint

Example:

{
  "id": "d9c88a0a-c0c8-4ec8-ade5-fde9106e5040",
  "chassis_id":"1e-a1-79-16-0a-6b",
  "port_id": "bf-f8-01-60-49-bc",
  "ip_address": "10.10.34.24",
  "attached_network_device": {
    "chassis_id": "7a-c9-d7-f0-e2-03",
    "port_id": "Ethernet 2/2"
  },
  "max_bandwidth": "10Gbit/s",
  "role": "sender",
  "label": "Video transmitter gateway endpoint."
}

HTTP status code 400

Returned when the PATCH request is incorrectly formatted or cannot be applied.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the requested Endpoint ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Delete an existing Endpoint.

URI Parameters

  • endpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

HTTP status code 204

Returned when the Endpoint is successfully deleted. No response body.

HTTP status code 404

Returned when the requested Endpoint ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 409

Returned when the operation cannot be performed because one or more Network Flows refer to this Endpoint. The Network Flows must be deleted first.

Body

Media type: application/json

Type: ErrorSchema

get

get

get

Get a single Network Link

Get a single Network Link

URI Parameters

  • networkLinkId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Link.

    Example:

    9468239c-afae-43eb-b711-bb7b8e817a83

HTTP status code 200

Body

Media type: application/json

Type: NetworkLink

Example:

{
  "id": "9468239c-afae-43eb-b711-bb7b8e817a83",
  "peers": [
    {
      "device_id": "f3841396-1cbf-4a8a-915c-dd1034121532",
      "port_id": "Ethernet 1/2"
    },
    {
      "device_id": "2c516096-4fa6-4b93-8b84-248ad79dff3a",
      "port_id": "Ethernet 2/1"
    }
  ],
  "speed": "100Gbit/s"
}

HTTP status code 404

Returned when the Network Link ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Network Flows

get

get

List Network Flows. NB: Query parameters should be implemented for all permitted resource attributes.

options get put patch delete

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

get

Get a single Network Flow

put

Create a Network Flow with the specified ID. Subsequent PUT requests should receive an error response. Updates should be done using PATCH.

patch

Update an existing Network Flow with the specified ID. A Network Flow is equivalent to and also uniquely identified by the Sender Endpoint ID and the multicast address, or the <S,G> pair. So, neither the Sender Endpoint ID nor the multicast address can be updated of an existing Network Flow. A new Network Flow should be created for a different pair of <S,G>. Moreover, for simplicity, receiver Endpoint IDs can only be updated using a /receivers POST or DELETE request.

delete

Delete the Network Flow with the specified ID.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

HTTP status code 200

HTTP status code 403

Get a single Network Flow

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

HTTP status code 200

Body

Media type: application/json

Type: NetworkFlow

Example:

{
  "id": "c386ff15-3b3f-4813-ac86-1c7b8cf753b6",
  "multicast_address": "226.1.1.1",
  "sender_endpoint_id": "a9ab3d49-3b8f-49e1-bbe4-b46228a9e167",
  "receiver_endpoint_ids": [
    "231ea016-1553-4488-8c2b-26bee7b9a1aa",
    "7e54a194-45e7-44e6-8795-b3a21bfff253"
  ],
  "bandwidth": "4Gbit/s",
  "profile": "SMPTE-2110-21-wide",
  "forward_flow": true,
  "dscp": "AF12",
  "label": "Sample Video network flow"
}

HTTP status code 404

Returned when the Network Flow ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Create a Network Flow with the specified ID. Subsequent PUT requests should receive an error response. Updates should be done using PATCH.

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

Body

Media type: application/json

Type: NetworkFlow

Example:

{
  "id": "1650fbcc-d8a0-4bd2-8e61-c7abb38d78d2",
  "multicast_address": "227.1.1.1",
  "sender_endpoint_id": "76beb838-3ad7-4011-bd68-5c203a4446ab",
  "receiver_endpoint_ids": [
    "3f80b3fa-74e3-4dcc-a1c0-5dbf5a199e20"
  ],
  "bandwidth": "4Gbit/s",
  "profile": "constant-rate",
  "forward_flow": false,
  "dscp": "AF11",
  "label": "New video network flow"
}

HTTP status code 201

Returned when the Network Flow is created successfully. The Location header should indicate the location of the created resource.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/{version}/network-flows/6fb3c057-a363-40cc-8f3d-cbaee5e35248

Body

Media type: application/json

Type: NetworkFlow

Example:

{
  "id": "c386ff15-3b3f-4813-ac86-1c7b8cf753b6",
  "multicast_address": "226.1.1.1",
  "sender_endpoint_id": "a9ab3d49-3b8f-49e1-bbe4-b46228a9e167",
  "receiver_endpoint_ids": [
    "231ea016-1553-4488-8c2b-26bee7b9a1aa",
    "7e54a194-45e7-44e6-8795-b3a21bfff253"
  ],
  "bandwidth": "4Gbit/s",
  "profile": "SMPTE-2110-21-wide",
  "forward_flow": true,
  "dscp": "AF12",
  "label": "Sample Video network flow"
}

HTTP status code 400

Returned when the PUT request is incorrectly formatted or has missing mandatory attributes or an attribute is invalid given the API's configuration, such as when the Network Flow ID already exists. Error responses should contain a relevant message.

Body

Media type: application/json

Type: ErrorSchema

Update an existing Network Flow with the specified ID. A Network Flow is equivalent to and also uniquely identified by the Sender Endpoint ID and the multicast address, or the <S,G> pair. So, neither the Sender Endpoint ID nor the multicast address can be updated of an existing Network Flow. A new Network Flow should be created for a different pair of <S,G>. Moreover, for simplicity, receiver Endpoint IDs can only be updated using a /receivers POST or DELETE request.

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a patch of a network flow.",
  "title": "Network flow with attributes that can be patched",
  "properties": {
    "bandwidth": {
      "type": "string",
      "description": "Average bandwidth requirement for the flow, formatted as a number followed by kbit/s, Mbit/s, Gbit/s. NB: Values should be formatted with no fraction component if possible, using the largest unit that allows that.",
      "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?[kMG]bit\\/s$"
    },
    "profile": {
      "description": "The transmission profile of the flow.",
      "type": "string",
      "enum": [
        "constant-rate",
        "SMPTE-2110-21-narrow",
        "SMPTE-2110-21-wide",
        "unknown"
      ]
    },
    "forward_flow": {
      "description": "Flag for forwarding the flow. If false, the network should not set up the flow. Only when this flag is changed to true should the flow be sent to all receivers.",
      "type": "boolean"
    },
    "dscp": {
      "type": "string",
      "description": "DSCP based QoS metrics number",
      "enum": [
        "CS0",
        "CS1",
        "CS2",
        "CS3",
        "CS4",
        "CS5",
        "CS6",
        "CS7",
        "AF11",
        "AF12",
        "AF13",
        "AF21",
        "AF22",
        "AF23",
        "AF31",
        "AF32",
        "AF33",
        "AF41",
        "AF42",
        "AF43",
        "EF"
      ]
    },
    "label": {
      "description": "Freeform string label for the network flow",
      "type": "string"
    }
  }
}

Example:

{
  "bandwidth": "4Gbit/s",
  "profile": "constant-rate",
  "forward_flow": true,
  "dscp": "AF11",
  "label": "Updated video network flow"
}

HTTP status code 200

Returned when the Network Flow is updated successfully. The updated Network Flow is returned in the response.

Body

Media type: application/json

Type: NetworkFlow

Example:

{
  "id": "c386ff15-3b3f-4813-ac86-1c7b8cf753b6",
  "multicast_address": "226.1.1.1",
  "sender_endpoint_id": "a9ab3d49-3b8f-49e1-bbe4-b46228a9e167",
  "receiver_endpoint_ids": [
    "231ea016-1553-4488-8c2b-26bee7b9a1aa",
    "7e54a194-45e7-44e6-8795-b3a21bfff253"
  ],
  "bandwidth": "4Gbit/s",
  "profile": "SMPTE-2110-21-wide",
  "forward_flow": true,
  "dscp": "AF12",
  "label": "Sample Video network flow"
}

HTTP status code 400

Returned when the PATCH request is incorrectly formatted or cannot be applied.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the Network Flow ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

Delete the Network Flow with the specified ID.

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

HTTP status code 204

Returned when the Network Flow is successfully deleted. No response body.

HTTP status code 404

Returned when the Network Flow ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

options post

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

post

Add one or more receivers to this Network Flow. Receivers included in the body should be appended to the existing receivers, if any. If the forward flow flag is set for this Network Flow, both bandwidth reservation and flow switching must occur for all new receivers. If the forward flow flag is not set, only resource reservation should take place. Failure to satisfy for any one receiver should fail for all and fail the complete request. Proper error message should be provided in this scenario. No task should be completed partially, that is, server should employ all-or-nothing strategy.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

HTTP status code 200

HTTP status code 403

Add one or more receivers to this Network Flow. Receivers included in the body should be appended to the existing receivers, if any. If the forward flow flag is set for this Network Flow, both bandwidth reservation and flow switching must occur for all new receivers. If the forward flow flag is not set, only resource reservation should take place. Failure to satisfy for any one receiver should fail for all and fail the complete request. Proper error message should be provided in this scenario. No task should be completed partially, that is, server should employ all-or-nothing strategy.

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Post request schema for adding new receiver endpoints.",
  "title": "One or many receivers to add to the resource.",
  "required": [
    "receiver_endpoint_ids"
  ],
  "properties": {
    "receiver_endpoint_ids": {
      "type": "array",
      "description": "List of receiver endpoint IDs.",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  }
}

Example:

{
  "receiver_endpoint_ids": [
    "ff458774-0fdc-4948-b0ee-2d6043c2c689",
    "4d3cfb9f-5a1b-4a92-a4f5-6f3812795629",
    "79b9e6ec-8d14-4c87-b1f1-45e763f4c077",
    "d60bbf82-6b5d-4a56-ab8e-eeae3e40e534",
    "e0cfe384-0a3e-4256-9a70-4251c423ad00"
  ]
}

HTTP status code 204

Returned when the receivers are successfully added. No response body.

HTTP status code 400

Returned when the POST request is incorrectly formatted, missing values, or an error occurred while adding the receivers. If the request failed due to a partial error, an appropriate message should be added in the error response.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the Network Flow ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

options delete

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

delete

Delete the receiver with the specified ID from this Network Flow.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db
  • receiverEndpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the receiver Endpoint.

    Example:

    77b52221-c789-45fd-90b3-d9d8211de9d3

HTTP status code 200

HTTP status code 403

Delete the receiver with the specified ID from this Network Flow.

URI Parameters

  • networkFlowId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Flow.

    Example:

    cfd02532-1c83-45a5-ae38-1cb7614346db
  • receiverEndpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the receiver Endpoint.

    Example:

    77b52221-c789-45fd-90b3-d9d8211de9d3

HTTP status code 204

Returned when the receiver is successfully deleted. No response body.

HTTP status code 404

Returned when no receiver with the specified ID exists for this Network Flow.

Body

Media type: application/json

Type: ErrorSchema

Network Address Translation policies

get

get

List Network Address Translation policies. NB: Query parameters should be implemented for all permitted resource attributes.

options get put patch delete

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

get

Get a single Network Address Translation policy

put

Create a Network Address Translation policy with the specified ID. Subsequent PUT requests should receive an error response.

patch

Update an existing Network Address Translation policy's attributes.

delete

Delete the Network Address Translation policy with the specified ID.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

HTTP status code 200

HTTP status code 403

Get a single Network Address Translation policy

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

HTTP status code 200

Body

Media type: application/json

Type: NetworkAddressTranslation

Example:

{
  "id": "b46fa060-a5fe-4144-94dc-24d5041c9f10",
  "label": "NAT S1-R3-video",
  "match": {
    "destination_ip": "239.1.2.3",
    "destination_port": 4500
  },
  "translated": {
    "destination_ip": "235.7.8.9",
    "destination_port": 10500
  },
  "receiver_endpoint_ids": [
    "b4aa4549-ef19-460b-9c93-76b41457af48"
  ]
}

HTTP status code 404

Returned when the Network Address Translation policy ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema

Create a Network Address Translation policy with the specified ID. Subsequent PUT requests should receive an error response.

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

Body

Media type: application/json

Type: NetworkAddressTranslation

Example:

{
  "id": "b46fa060-a5fe-4144-94dc-24d5041c9f10",
  "label": "NAT S1-R3-video",
  "match": {
    "destination_ip": "239.1.2.3",
    "destination_port": 4500
  },
  "translated": {
    "destination_ip": "235.7.8.9",
    "destination_port": 10500
  },
  "receiver_endpoint_ids": [
    "b4aa4549-ef19-460b-9c93-76b41457af48"
  ]
}

HTTP status code 201

Returned when the Network Address Translation policy is created successfully. The Location header should indicate the location of the created resource.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/{version}/network-address-translations/b46fa060-a5fe-4144-94dc-24d5041c9f10

Body

Media type: application/json

Type: NetworkAddressTranslation

Example:

{
  "id": "b46fa060-a5fe-4144-94dc-24d5041c9f10",
  "label": "NAT S1-R3-video",
  "match": {
    "destination_ip": "239.1.2.3",
    "destination_port": 4500
  },
  "translated": {
    "destination_ip": "235.7.8.9",
    "destination_port": 10500
  },
  "receiver_endpoint_ids": [
    "b4aa4549-ef19-460b-9c93-76b41457af48"
  ]
}

HTTP status code 400

Returned when the PUT request is incorrectly formatted or has missing mandatory attributes or an attribute is invalid given the API's configuration, such as when the Network Address Translation policy ID already exists. Error responses should contain a relevant message.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema

Update an existing Network Address Translation policy's attributes.

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a patch of a network address translation policy.",
  "title": "Schema to modify a network address translation policy.",
  "properties": {
    "label": {
      "description": "Translation policy name.",
      "type": "string"
    }
  }
}

Example:

{
  "label": "NAT S1-R3-video (both destination IP address and port must match for this policy to be applied)"
}

HTTP status code 200

Returned when the Network Address Translation policy is updated successfully. The updated Network Address Translation policy is returned in the response.

Body

Media type: application/json

Type: NetworkAddressTranslation

Example:

{
  "id": "b46fa060-a5fe-4144-94dc-24d5041c9f10",
  "label": "NAT S1-R3-video (both destination IP address and port must match for this policy to be applied)",
  "match": {
    "destination_ip": "239.1.2.3",
    "destination_port": 4500
  },
  "translated": {
    "destination_ip": "235.7.8.9",
    "destination_port": 10500
  },
  "receiver_endpoint_ids": [
    "b4aa4549-ef19-460b-9c93-76b41457af48"
  ]
}

HTTP status code 400

Returned when the PATCH request is incorrectly formatted or cannot be applied.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the requested Network Address Translation policy ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema

Delete the Network Address Translation policy with the specified ID.

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

HTTP status code 204

Returned when the Network Address Translation policy is successfully deleted. No response body.

HTTP status code 404

Returned when the Network Address Translation policy ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema

options post

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

post

Add one or more receivers to this Network Address Translation policy. Receivers included in the body should be appended to the existing receivers, if any.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

HTTP status code 200

HTTP status code 403

Add one or more receivers to this Network Address Translation policy. Receivers included in the body should be appended to the existing receivers, if any.

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Post request schema for adding new receiver endpoints.",
  "title": "One or many receivers to add to the resource.",
  "required": [
    "receiver_endpoint_ids"
  ],
  "properties": {
    "receiver_endpoint_ids": {
      "type": "array",
      "description": "List of receiver endpoint IDs.",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  }
}

Example:

{
  "receiver_endpoint_ids": [
    "ff458774-0fdc-4948-b0ee-2d6043c2c689",
    "4d3cfb9f-5a1b-4a92-a4f5-6f3812795629",
    "79b9e6ec-8d14-4c87-b1f1-45e763f4c077",
    "d60bbf82-6b5d-4a56-ab8e-eeae3e40e534",
    "e0cfe384-0a3e-4256-9a70-4251c423ad00"
  ]
}

HTTP status code 204

Returned when the receivers are successfully added. No response body.

HTTP status code 400

Returned when the POST request is incorrectly formatted, missing values, or an error occurred while adding the receivers. If the request failed due to a partial error, an appropriate message should be added in the error response.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the Network Address Translation policy ID does not exist.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema

options delete

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

delete

Delete the receiver with the specified ID from this Network Address Translation policy.

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10
  • receiverEndpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the receiver Endpoint.

    Example:

    77b52221-c789-45fd-90b3-d9d8211de9d3

HTTP status code 200

HTTP status code 403

Delete the receiver with the specified ID from this Network Address Translation policy.

URI Parameters

  • policyId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the Network Address Translation policy.

    Example:

    b46fa060-a5fe-4144-94dc-24d5041c9f10
  • receiverEndpointId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

    The globally unique identifier for the receiver Endpoint.

    Example:

    77b52221-c789-45fd-90b3-d9d8211de9d3

HTTP status code 204

Returned when the receiver is successfully deleted. No response body.

HTTP status code 404

Returned when no receiver with the specified ID exists for this Network Address Translation policy.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 501

The NAT functionality is not supported by this implementation.

Body

Media type: application/json

Type: ErrorSchema