AMWA IS-06 NMOS Network-control-API API documentation version v1.0

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

  • version: required(v1.0)

Overview

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

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: any

Example:

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

Network Devices

get

get

List all network devices.

get

get

Get a single Network Device

Get a single Network Device

URI Parameters

  • id: 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 with the guid does not exist.

Body

Media type: application/json

Type: ErrorSchema

Endpoints

get

get

Retrieve a collection of endpoints.

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 schema includes mandatory 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 capabale) or manual entry in the caller of this API (e.g., broadcast controller). The network may verify these details for security purposes. Verification may happen synchronously, as part of the request. Network controller must create a corresponding network link with this endpoint as the peer device. Peer port id of the new link may or maynot be assigned, i.e, implementation dependent. Subsequent PUT requests should throw error. Updates should be done using PATCH.

patch

Update an existing endpoint attributes.

delete

Delete an existing endpoint.

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

URI Parameters

  • id: 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 endpoint.

    Example:

    3607f868-c762-4220-8caf-e5a546395b29

HTTP status code 200

HTTP status code 403

HTTP status code 404

Get a single Endpoint

URI Parameters

  • id: 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 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 Node 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 schema includes mandatory 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 capabale) or manual entry in the caller of this API (e.g., broadcast controller). The network may verify these details for security purposes. Verification may happen synchronously, as part of the request. Network controller must create a corresponding network link with this endpoint as the peer device. Peer port id of the new link may or maynot be assigned, i.e, implementation dependent. Subsequent PUT requests should throw error. Updates should be done using PATCH.

URI Parameters

  • id: 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 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

Returns when the endpoint is registered with network controller successfully. Header should indicate the location of the created resource.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/v1.0/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 missing mandatory attributes. Also when an endpoint with this guid already exists. Errors should contain relevant msg.

Body

Media type: application/json

Type: ErrorSchema

Update an existing endpoint attributes.

URI Parameters

  • id: 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 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.",
  "required": [
  ],
  "properties": {
    "ip_address": {
      "type": "string",
      "description": "IP address on which the endpoint sends/receives flows. IP must be unique in the network.",
      "anyOf": [
        {
          "format": "ipv4"
        },
        {
          "format": "ipv6"
        }
      ]
    },
    "attached_network_device": {
      "type": "object",
      "description": "Peer network device (switch) details. This can not be an endpoint.",
      "required": [
        "chassis_id",
        "port_id"
      ],
      "properties": {
        "chassis_id": {
          "type": "string",
          "description": "MAC address for the peer network device.",
          "pattern": "^([0-9a-f]{2}[-]){5}([0-9a-f]{2})$"
        },
        "port_id": {
          "type": "string",
          "description": "The ifAlias of the peer network device the end point is connected to."
        }
      }
    },
    "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. Format as numbers followed by kbit/s, Mbit/s, Gbit/s."
    },
    "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 can not be updated.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the requested Endpoint with guid does not exist.

Body

Media type: application/json

Type: ErrorSchema

Delete an existing endpoint.

URI Parameters

  • id: 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 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 with guid does not exist

get

Network flow

get

get

Retrieve a collection of network flows.

options get put patch delete

options

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

get

Retrieve a single network-flow with the specified guid.

put

Create a network flow with the specific guid. No subsequent PUT request should be made for this flow and should return error. Use PATCH to update existing network flow.

patch

Update an existing network flow with the specific guid. A network flow is equivalent to and uniquely identified by the sender id and the multicast address, or the <S,G> pair. So, neither the sender id or the multicast address can be updated of an existing 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 /receivers post or delete request.

delete

Delete the network-flow with the specified guid.

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

URI Parameters

  • id: 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

HTTP status code 404

Retrieve a single network-flow with the specified guid.

URI Parameters

  • id: 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 with guid does not exist.

Body

Media type: application/json

Type: ErrorSchema

Create a network flow with the specific guid. No subsequent PUT request should be made for this flow and should return error. Use PATCH to update existing network flow.

URI Parameters

  • id: 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. Response body is same as 200 on GET. Location header should indicate the location of the network flow.

Headers

  • Location: required(string)

    Example:

    /x-nmos/netctrl/v1.0/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 values. Also returned when a network-flow exists with the given guid. Explicit message should be added to indicate the cause of the error.

Body

Media type: application/json

Type: ErrorSchema

Update an existing network flow with the specific guid. A network flow is equivalent to and uniquely identified by the sender id and the multicast address, or the <S,G> pair. So, neither the sender id or the multicast address can be updated of an existing 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 /receivers post or delete request.

URI Parameters

  • id: 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",
  "required": [
  ],
  "properties": {
    "bandwidth": {
      "type": "string",
      "description": "Average bandwidth requirement for the flow. Format as number followed by kbit/s, Mbit/s, Gbit/s.",
      "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",
      "default": true
    },
    "dscp": {
      "type": "string",
      "description": "DSCP based QoS metrics number, default is CS0, best effort.",
      "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 has incorrect values.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the network-flow with guid does not exist.

Body

Media type: application/json

Type: ErrorSchema

Delete the network-flow with the specified guid.

URI Parameters

  • id: 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 with guid 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 is set for this network flow, both bandwidth resrvation and flow switching must occur for all new receivers. If the fowrad-flow 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

  • id: 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

HTTP status code 404

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 is set for this network flow, both bandwidth resrvation and flow switching must occur for all new receivers. If the fowrad-flow 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

  • id: 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 receivers to an existing network flow.",
  "title": "One or many receivers for a multicast network-flow.",
  "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 partial error, appropriate message should be added in error response.

Body

Media type: application/json

Type: ErrorSchema

HTTP status code 404

Returned when the network flow with guid 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 receiver of this network flow with given id.

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

URI Parameters

  • id: 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
  • receiverId: 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

HTTP status code 404

Delete receiver of this network flow with given id.

URI Parameters

  • id: 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
  • receiverId: 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 specifid id exists for this flow.

Body

Media type: application/json

Type: ErrorSchema