Merge pull request #69 from AMWA-TV/garethsb-network-link-1

Tighten up network-links endpoint to describe inter-switch links only

Author: Networks Engineering & Operations Advanced Technology (Disney)

APIs/NetworkControlAPI.raml

@@ -172,7 +172,6 @@ documentation:
         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.
-        The network controller _should_ create a corresponding Network Link with this Endpoint as the peer device.
         Subsequent PUT requests should receive an error response. Updates should be done using PATCH.
       body:
         type: Endpoint
@@ -222,7 +221,7 @@ documentation:
           body:
             type: ErrorSchema
     delete:
-      description: Delete an existing Endpoint. On a successful request, the network controller _must_ also delete the corresponding Network Link.
+      description: Delete an existing Endpoint.
       responses:
         204:
           description: >
@@ -241,9 +240,9 @@ documentation:
     is: [paged]
     description: |
       List Network Links.
-      Get all links in the network. Network Links are always bidirectional. The implementation of the API must ensure that query results are independent of how a bi-directional link is persisted.
       NB: Query parameters should be implemented for all permitted resource attributes.
     queryParameters:
+      id:
       peers.device_id:
       peers.port_id:
       speed:
@@ -256,6 +255,24 @@ documentation:
         description: The query parameters specified are not currently supported by this implementation.
         body:
           type: ErrorSchema
+  /{networkLinkId}:
+    uriParameters:
+      networkLinkId:
+        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}$"
+        description: The globally unique identifier for the Network Link.
+        example: 9468239c-afae-43eb-b711-bb7b8e817a83
+    get:
+      description: Get a single Network Link
+      responses:
+        200:
+          body:
+            type: NetworkLink
+            example: !include ../examples/netctrl-network-link-id-get-200.json
+        404:
+          description: Returned when the Network Link ID does not exist.
+          body:
+            type: ErrorSchema
 /network-flows:
   displayName: Network Flows
   get:

APIs/schemas/network-link.json

@@ -1,14 +1,20 @@
 {
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
-  "description": "Describes a network link. A network link consists of two peers. A peer is either a network device or an endpoint. But a link cannot have two endpoints as peers. Links are always bidirectional. That is, the order of the peers in this entity carries no special meaning. When a link is between a network device (switch) and an endpoint, the port_id for the endpoint peer must be null.",
+  "description": "Describes a network link. A network link consists of two peers. Each peer in the link must be a network device, links between network devices and endpoints are not represented. Links are always bidirectional. That is, the order of the peers in this entity carries no special meaning.",
   "required": [
+    "id",
     "peers",
     "speed"
   ],
   "properties": {
+    "id": {
+      "description": "Globally unique identifier for the network link",
+      "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}$"
+    },
     "peers": {
-      "description": "List of peer devices in a link. Peer can be a network device (switch) or an endpoint. There must be exactly two peers in the list.",
+      "description": "List of peers in a link. Each peer is a network device (switch). There must be exactly two peers in the list.",
       "type": "array",
       "items": {
         "type": "object",
@@ -18,12 +24,12 @@
         ],
         "properties": {
           "device_id": {
-            "description": "Globally unique identifier of a network device or an endpoint.",
+            "description": "Globally unique identifier of a network device.",
             "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}$"
           },
           "port_id": {
-            "description": "When the peer is a network device, matches the port_id of the interface on the network device to which the link is connected. When the peer is an endpoint, this value must be null.",
+            "description": "Matches the port_id of the interface of the network device to which the link is connected.",
             "anyOf": [
               {
                 "type": "string",
@@ -34,10 +40,6 @@
                 "type": "string",
                 "pattern": "^.+$",
                 "description": "When the Port ID is anything other than a MAC address, a freeform string may be used."
-              },
-              {
-                "type": "null",
-                "description": "When the peer is an endpoint (instead of network device) the port_id MUST be null. A null value will explicitly identify this peer as an endpoint. An endpoint has only one port, so a port_id value is redundant."
               }
             ]
           }

docs/2.3. APIs - Query Parameters.md

@@ -367,7 +367,7 @@ GET /x-nmos/netctrl/v1.0/endpoints?role=sender&chassis_id=2d-af-a9-41-01-b4
 ```
 
 ***Response***
-* Returns all Endpoint objects which have an attribute of 'role' which exactly matches 'sender' AND a 'chassi_is' attribute which exactly matches '2d-af-a9-41-01-b4'.
+* Returns all Endpoint objects which have an attribute of 'role' which exactly matches 'sender' AND a 'chassis_id' attribute which exactly matches '2d-af-a9-41-01-b4'.
 
 **Example 3: Querying Within Objects**
 

docs/3.0. Data Model.md

@@ -36,4 +36,4 @@ The `chassis_id` parameter may be used to generate a persistent, unique `id` for
 
 ### Network Link
 
-Network Links do not have a unique `id`. They are identified by the peer devices in the link.
+The `chassis_id` and `port_id` of the `peers` may be used to generate a persistent, unique `id` for a Network Link.

docs/3.4. Data Model - Network Link.md

@@ -2,16 +2,12 @@
 
 _(c) AMWA 2017, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)_
 
-A Network Link represents the bidirectional link between a [Network Device](3.3.%20Data%20Model%20-%20Network%20Device.md) and another Network Device or the link between the Network Device and the [Endpoint](3.1.%20Data%20Model%20-%20Endpoint.md).
+A Network Link represents the bidirectional link between a [Network Device](3.3.%20Data%20Model%20-%20Network%20Device.md) and another Network Device.
 
 The parameters of a Network Link are:
 
-* `peers`: an array of exactly two objects identifying a network device interface (by its `device_id` and `port_id`) or endpoint (by id) and the peer network device
+* `peers`: an array of exactly two objects identifying a network device interface (by its `device_id` and `port_id`) and the peer network device interface
 * `speed`: the speed of the link
 
-![Class Diagram](images/Network-Link.png)
-
-The only operation permitted for this resource is GET. When a broadcast controller performs a GET operation with a `device_id` query parameter, the network controller returns all the links that originate/terminate in the specified network device or endpoint.
-As these links are bi-directional, the same link information will be reported by both network devices when a GET operation is performed for neighboring network devices.
-
-![Class Diagram](images/Bidirectional-Links.png)
+The only operation permitted for this resource is GET. When a broadcast controller performs a GET operation with a `device_id` query parameter, the network controller returns all the links that originate/terminate in the specified network device.
+As these links are bi-directional, a link will be reported when a GET operation is performed for either peer network device.

docs/images/Bidirectional-Links.png

@@ -0,0 +1,14 @@
+{
+  "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"
+}

docs/images/EP-Auth.png

@@ -1,5 +1,6 @@
 [
   {
+    "id": "9468239c-afae-43eb-b711-bb7b8e817a83",
     "peers": [
       {
         "device_id": "f3841396-1cbf-4a8a-915c-dd1034121532",
@@ -13,6 +14,7 @@
     "speed": "100Gbit/s"
   },
   {
+    "id": "a5b16a69-b64c-4bb4-816d-07c9701140eb",
     "peers": [
       {
         "device_id": "aa4df211-284e-4417-9827-b1ceda12a4ff",
@@ -26,6 +28,7 @@
     "speed": "100Gbit/s"
   },
   {
+    "id": "abc0ca32-f723-45e4-a143-b23e3b3ad7e7",
     "peers": [
       {
         "device_id": "cf333591-82ac-456a-898b-f56ff83d1d22",
@@ -39,6 +42,7 @@
     "speed": "1Gbit/s"
   },
   {
+    "id": "b7bacccd-d433-4133-a0e3-b4d383212ba1",
     "peers": [
       {
         "device_id": "71706c18-49f2-481d-914a-d711d773dacb",