Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame^] | 1 | .. vim: syntax=rst |
| 2 | |
| 3 | Aether ROC Control API |
| 4 | ====================== |
| 5 | |
| 6 | Background |
| 7 | ---------- |
| 8 | |
| 9 | The Aether ROC control API is available via REST or via gNMI. It is expected that most external |
| 10 | consumers of the API will use REST. |
| 11 | |
| 12 | The REST API supports the typical GET, POST, PATCH, DELETE operations: |
| 13 | |
| 14 | * GET. Retrieve an object. |
| 15 | * POST. Create an object. |
| 16 | * PUT, PATCH. Modify an existing object. |
| 17 | * DELETE. Delete an object. |
| 18 | |
| 19 | Endpoints are named based on the type of object. Some examples: |
| 20 | |
| 21 | * `GET http://roc/aether/v3.0.0/connectivity-service-v3/enterprise/`. Get a list of enterprises. |
| 22 | * `GET http://roc/aether/v3.0.0/connectivity-service-v3/enterprise/Starbucks`. Get the Starbucks enterprise. |
| 23 | * `POST http://roc/aether/v3.0.0/connectivity-service-v3/enterprise`. Create a new enterprise. |
| 24 | * `PATCH http://roc/aether/v3.0.0/connectivity-service-v3/site/Starbucks-NewYork`. Update the Starbucks New York site. |
| 25 | |
| 26 | This document is a high-level description of the objects that can be interacted with. For a |
| 27 | low-level description, see the Swagger API specification. |
| 28 | |
| 29 | Identifying and Referencing Objects |
| 30 | ----------------------------------- |
| 31 | |
| 32 | Every object contains an `id` that is used to identify the object. The `id` is only unique within |
| 33 | the scope of a particular type of object. For example, a site may be named `foo` and a device-group |
| 34 | may also be named `foo`, and the two names do not conflict because they are different object types. |
| 35 | |
| 36 | Some objects contain references to other objects. For example, many objects contain references to |
| 37 | the `Enterprise` object, which allows them to be associated with a particular enterprise. References |
| 38 | are constructed using the `id` field of the referenced object. It is an error to attempt to create |
| 39 | a reference to an object that does not exist. Deleting an object while there are open references |
| 40 | to it from other objects is also an error. |
| 41 | |
| 42 | Common Model Fields |
| 43 | ------------------- |
| 44 | |
| 45 | Several fields are common to all models in Aether: |
| 46 | |
| 47 | * `id`. The identifier for objects of this model. |
| 48 | * `description`. A human-readable description, used to store additional context about the object. |
| 49 | * `display-name`. A human-readable name that is shown in the GUI. |
| 50 | |
| 51 | As these fields are common to all models, they will be omitted from the per-model descriptions below. |
| 52 | |
| 53 | Key Aether Objects |
| 54 | ------------------ |
| 55 | |
| 56 | The following is a list of Aether models, generally organized in a top-down manner. |
| 57 | |
| 58 | Enterprise |
| 59 | ~~~~~~~~~~ |
| 60 | |
| 61 | `Enterprise` forms the root of a customer-specific Enterprise hierarchy. The `Enterprise` model is |
| 62 | referenced by many other objects, and allows those objects to be scoped to a particular Enterprise |
| 63 | for ownership and role-based access control purposes. `Enterprise` contains the following fields: |
| 64 | |
| 65 | * `connectivity-service`. A list of connectivity services that realize connectivity for this |
| 66 | enterprise. A connectivity service is a reference to the sdcore, and reflects either a 4G or a |
| 67 | 5G core. |
| 68 | |
| 69 | Site |
| 70 | ~~~~ |
| 71 | |
| 72 | `Enterprises` are further divided into `Sites`. A site is a point of presence for an `Enterprise` and |
| 73 | may be either physical or logical (i.e. a single geographic location could in theory contain several |
| 74 | logical sites). Site contains the following fields: |
| 75 | |
| 76 | * `enterprise`. A link to the `Enterprise` that owns this site. |
| 77 | * `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following |
| 78 | sub-fields: |
| 79 | |
| 80 | * `mcc`. Mobile country code. |
| 81 | * `mnc`. Mobile network code. |
| 82 | * `enterprise`. A numeric enterprise id. |
| 83 | * `format`. A mask that allows the above three fields to be embedded into an IMSI. For example |
| 84 | `CCCNNNEEESSSSSS` will construct IMSIs using a 3-digit MCC, 3-digit MNC, 3-digit ENT, and a |
| 85 | 6-digit subscriber. |
| 86 | |
| 87 | Device-Group |
| 88 | ~~~~~~~~~~~~ |
| 89 | |
| 90 | `Device-Group` allows multiple devices to be logically grouped together. `Device-Group` contains |
| 91 | the following fields: |
| 92 | |
| 93 | * `imsis`. A list of IMSI ranges. Each range has the following |
| 94 | fields: |
| 95 | |
| 96 | * `name`. Name of the range. Used as a key. |
| 97 | * `imsi-range-from`. First subscriber in the range. |
| 98 | * `imsi-range-to`. Last subscriber in the range. Can be omitted if the range only contains one |
| 99 | IMSI. |
| 100 | * `ip-domain`. Reference to an `IP-Domain` object that describes the IP and DNS settings for UEs |
| 101 | within this group. |
| 102 | * `site`. Reference to the site where this `Device-Group` may be used. Indirectly identifies the |
| 103 | `Enterprise` as `Site` contains a reference to `Enterprise`. |
| 104 | |
| 105 | Virtual Cellular Service |
| 106 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 107 | |
| 108 | `Virtual Cellular Service (VCS)` connects a `Device-Group` to an `Application`. `VCS` has the |
| 109 | following fields: |
| 110 | |
| 111 | * `device-group`. A list of `Device-Group` objects that can participate in this `VCS`. Each |
| 112 | entry in the list contains both the reference to the `Device-Group` as well as an `enable` |
| 113 | field which may be used to temporarily remove access to the group. |
| 114 | * `application`. A list of `Application` objects that are either allowed or denied for this |
| 115 | `VCS`. Each entry in the list contains both a reference to the `Application` as well as an |
| 116 | `allow` field which can be set to `true` to allow the application or `false` to deny it. |
| 117 | * `template`. Reference to the `Template` that was used to initialize this `VCS`. |
| 118 | * `upf`. Reference to the User Plane Function (`UPF`) that should be used to process packets |
| 119 | for this `VCS`. It's permitted for multiple `VCS` to share a single `UPF`. |
| 120 | * `ap`. Reference to an Access Point List (`AP-List`) that lists the access points for this |
| 121 | `VCS`. |
| 122 | * `enterprise`. Reference to the `Enterprise` that owns this `VCS`. |
| 123 | * `SST`, `SD`, `uplink`, `downlink`, `traffic-class`. Parameters that were initialized using the |
| 124 | `template`. They are described in the section for the `Template` model. |
| 125 | |
| 126 | Application |
| 127 | ~~~~~~~~~~~ |
| 128 | |
| 129 | `Application` specifies an application and the endpoints for the application. Applications are |
| 130 | the termination point for traffic from the UPF. Contains the following fields: |
| 131 | |
| 132 | * `endpoint`. A list of endpoints. Each has the following |
| 133 | fields: |
| 134 | |
| 135 | * `name`. Name of the endpoint. Used as a key. |
| 136 | * `address`. The DNS name or IP address of the endpoint. |
| 137 | * `port-start`. Starting port number. |
| 138 | * `port-end`. Ending port number. |
| 139 | * `protocol`. `TCP|UDP`, specifies the protocol for the endpoint. |
| 140 | * `enterprise`. Link to an `Enterprise` object that owns this application. May be left empty |
| 141 | to indicate a global application that may be used by multiple enterprises. |
| 142 | |
| 143 | Supporting Aether Objects |
| 144 | ------------------------- |
| 145 | |
| 146 | AP-List |
| 147 | ~~~~~~~ |
| 148 | |
| 149 | `AP-List` specifies a list of access points (radios). It has the following fields: |
| 150 | |
| 151 | * `access-points`. A list of access points. Each access point has the following: |
| 152 | |
| 153 | * `address`. Hostname of the access point. |
| 154 | * `tac`. Type Allocation Code. |
| 155 | * `enable`. If set to `true`, the access point is enabled. Otherwise, it is disabled. |
| 156 | |
| 157 | * `enterprise`. The `Enterprise` that owns these access points. |
| 158 | |
| 159 | Connectivity-Service |
| 160 | ~~~~~~~~~~~~~~~~~~~~ |
| 161 | |
| 162 | `Connectivity-Service` specifies the URL of an sd-core control plane. |
| 163 | |
| 164 | * `core-5g-endpoint`. Endpoint of a `config4g` or `config5g` core. |
| 165 | |
| 166 | IP-Domain |
| 167 | ~~~~~~~~~ |
| 168 | |
| 169 | `IP-Domain` specifies IP and DNS settings and has the following fields: |
| 170 | |
| 171 | * `dnn`. Data network name for 5G, or APN for 4G. |
| 172 | * `dns-primary`, `dns-secondary`. IP addresses for DNS servers. |
| 173 | * `subnet`. Subnet to allocate to UEs. |
| 174 | * `admin-status`. Tells whether these ip-domain settings should be used, or whether they |
| 175 | should be drained from UEs. |
| 176 | * `mtu`. Ethernet maximum transmission unit. |
| 177 | * `enterprise`. `Enterprise that owns this `IP-Domain`. |
| 178 | |
| 179 | Template |
| 180 | ~~~~~~~~ |
| 181 | |
| 182 | `Template` contains connectivity settings that are pre-configured by Aether Operations. |
| 183 | Templates are used to initialize `VCS` objects. `Template` has the following fields: |
| 184 | |
| 185 | * `sst`, `sd`. Slice identifiers. |
| 186 | * `uplink`, `downlink`. Guaranteed uplink and downlink bandwidth. |
| 187 | * `traffic-class`. Link to a `Traffic-Class` object that describes the type of traffic. |
| 188 | |
| 189 | Traffic-Class |
| 190 | ~~~~~~~~~~~~~ |
| 191 | |
| 192 | Specifies the class of traffic. Contains the following: |
| 193 | |
| 194 | * `qci`. QoS class identifier. |
| 195 | * `pelr`. Packet error loss rate. |
| 196 | * `pdb`. Packet delay budget. |
| 197 | |
| 198 | UPF |
| 199 | ~~~ |
| 200 | |
| 201 | Specifies the UPF that should forward packets. Has the following fields: |
| 202 | |
| 203 | * `address`. Hostname or IP address of UPF. |
| 204 | * `port`. Port number of UPF. |
| 205 | * `enterprise`. Enterprise that owns this UPF. |