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