Aether-3438 add docs about how to add a new enterprise
Change-Id: I049b15bb3b1be9e4676dce93426623c561e1f41a
diff --git a/developer/roc-api.rst b/developer/roc-api.rst
index 98088e2..06a937b 100644
--- a/developer/roc-api.rst
+++ b/developer/roc-api.rst
@@ -10,6 +10,8 @@
e.g. on a local system (if the GUI has been port-forwarded on port 8183)
*http://localhost:8183/aether-roc-api/*
+For Aether-In-A-Box deployment the API can be found at *http://<hostname>:31194/aether-roc-api/*
+
On the Production system it would be *https://roc.aetherproject.org/aether-roc-api/*
.. note:: Opening this in a browser will display a HTML view of the API (powered by *ReDoc*).
@@ -33,27 +35,31 @@
Endpoints are named based on the type of object. Some examples:
-* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Get a list of enterprises.
-* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/starbucks`. Get the Starbucks enterprise.
-* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Create a new enterprise.
-* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/enterprise/starbucks/site/starbucks-newyork`. Update the Starbucks New York site.
+* `GET http://roc/targets`. Get a list of enterprises.
+* `GET http://roc/aether/v2.1.0/starbucks/application`. Get the list of applications in the Starbucks enterprise.
+* `GET http://roc/aether/v2.1.0/starbucks/site`. Get the list of sites in the Starbucks enterprise.
+* `GET http://roc/aether/v2.1.0/starbucks/site/starbucks-seattle`. Get details of the 'seattle' site in the Starbucks enterprise.
+* `POST http://roc/aether/v2.1.0/starbucks/site/newsite`. Create a new (or update existing) site in the Starbucks enterprise.
This document is a high-level description of the objects that can be interacted with. For a
low-level description, see the specification (:ref:`developer/roc-api:Access` section above).
+Enterprises
+------------
+The API is segmented by `enterprise`, as the Aether ROC is a multi Tenant system. Each of the URLs shown
+above has an example enterprise built in to the path. If a valid enterprise is not given, the results will
+be empty.
+
Identifying and Referencing Objects
-----------------------------------
-Every object contains an `id` that is used to identify the object. The `id` is only unique within
-the scope of a particular type of object. For example, a site may be named `foo` and a device-group
-may also be named `foo`, and the two names do not conflict because they are different object types.
-The `id` is model specific. For example, a site has a `site-id` and an slice has a
+Every object contains an `id` - for example, a site has a `site-id` and an slice has a
`slice-id`. The models are generally nested, for example `slice` is a member of `site`, which in
-turn is a member of `enterprise`.
+turn belongs to an `enterprise`.
-In addition to the `id`, most identifiable objects also include a `display-name`. The `display-name`
-may be changed at any time by the user without affecting behavior. In contrast, the `id` is immutable,
-and the only way to change an `id` is to delete the object and make a new one.
+In addition to an `id`, most identifiable objects also include a `display-name` and a `description`.
+The `display-name` may be changed at any time by the user without affecting behavior. In contrast,
+the `id` is immutable, and the only way to change an `id` is to delete the object and make a new one.
Some objects contain references to other objects. References
are constructed using the `id` field of the referenced object. It is an error to attempt to create
@@ -65,34 +71,22 @@
Several fields are common to all models in Aether:
-* `<modelname>-id`. The identifier for objects of this model.
+* `<objectname>-id`. The identifier for objects.
* `description`. A human-readable description, used to store additional context about the object.
* `display-name`. A human-readable name that is shown in the GUI.
-As these fields are common to all models, they will be omitted from the per-model descriptions below.
+As these fields are common to all objects, they will be omitted from the per-object descriptions below.
Key Aether Objects
------------------
-The following is a list of Aether models, generally organized in a top-down manner.
-
-Enterprise
-~~~~~~~~~~
-
-`Enterprise` forms the root of a customer-specific Enterprise hierarchy. The `Enterprise` model is
-referenced by many other objects, and allows those objects to be scoped to a particular Enterprise
-for ownership and role-based access control purposes. `Enterprise` contains the following fields:
-
-* `connectivity-service`. A list of connectivity services that realize connectivity for this
- enterprise. A connectivity service is a reference to the SD-Core, and reflects either a 4G or a
- 5G core.
+The following is a list of Aether models elements (objects), generally organized in a top-down manner.
Site
~~~~
-`Enterprises` are further divided into `Sites`. A site is a point of presence for an `Enterprise` and
-may be either physical or logical (i.e. a single geographic location could in theory contain several
-logical sites). Site contains the following fields:
+A site is a point of presence for an `Enterprise` and may be either physical or logical (i.e. a single
+geographic location could in theory contain several logical sites). Site contains the following fields:
* `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following
sub-fields:
@@ -104,13 +98,6 @@
`CCCNNNEEESSSSSS` will construct IMSIs using a 3-digit MCC, 3-digit MNC, 3-digit ENT, and a
6-digit subscriber.
-* `small-cell` A list of 5G gNodeB or Access Point or Radios. Each small cell has the following:
-
- * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields.
- * `address`. Hostname of the small cell.
- * `tac`. Type Allocation Code.
- * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled.
-
* `monitoring` Configuration of how the monitoring framework of the site can be connected:
* `edge-cluster-prometheus-url` the URL of the site's Edge cluster Prometheus service
@@ -122,6 +109,27 @@
be used for the `display-name` as a convention.
* `description` an optional description
+The site also contains sub objects like:
+
+* Devices
+* Device Group
+* IP Domain
+* Sim Card
+* Small Cell
+* Slice
+* UPF
+
+Device
+~~~~~~
+
+A device represents a UE (User Equipment) registered on the Aether system. The devices are then referenced
+by the `device-group` object.
+
+* imei - the International Mobile Equipment Identifier of the device
+* sim-card - a reference to the `sim-card` object
+* state - a set of attributes that report the state of the device - includes `ip-address`,
+ `connected` and `last-connected`
+
Device-Group
~~~~~~~~~~~~
@@ -139,6 +147,25 @@
* `traffic-class`. The traffic class to be used for devices in this group.
+SIM Card
+~~~~~~~~
+The Sim Card is used to represent a subscriber in the Aether system. When provisioned correctly there is
+a 1:1 relationship between SIM Card and Device, with the identifier of the SIM Card being defined in the
+Device
+
+* `iccid` - the Integrated Circuit Card Identifier - which should be unique to any SIM Card
+* `imsi` - the International Mobile Subscriber Identifier - the identifier of the Subscriber in Aether
+
+Small Cell
+~~~~~~~~~~
+
+`Small cell` is list of 5G gNodeB or Access Point or Radios. Each small cell has the following:
+
+ * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields.
+ * `address`. Hostname of the small cell.
+ * `tac`. Type Allocation Code.
+ * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled.
+
Slice
~~~~~
@@ -163,10 +190,12 @@
* `mbr.uplink-burst-size`, `mbr.downlink-burst-size`. Maximum burst sizes in bytes for
the maximum bit rates.
+
Application
~~~~~~~~~~~
-`Application` specifies an application and the endpoints for the application. Applications are
+`Application` specifies an application and the endpoints for the application. Applications are be shared
+across Sites for an enterprise, and so are defined at the top level of the model. Applications are
the termination point for traffic from the UPF. Contains the following fields:
* `address`. The DNS name or IP address of the endpoint.
@@ -187,18 +216,11 @@
Supporting Aether Objects
-------------------------
-Connectivity-Service
-~~~~~~~~~~~~~~~~~~~~
-
-`Connectivity-Service` specifies the URL of an SD-Core control plane.
-
-* `core-5g-endpoint`. Endpoint of a `config4g` or `config5g` core.
-* `acc-prometheus-url`. Prometheus endpoint where metrics may be queried regarding this connectivity service.
IP-Domain
~~~~~~~~~
-`IP-Domain` specifies IP and DNS settings and has the following fields:
+`IP-Domain` (beneath Site) specifies IP and DNS settings and has the following fields:
* `dnn`. Data network name for 5G, or APN for 4G.
* `dns-primary`, `dns-secondary`. IP addresses for DNS servers.
@@ -212,7 +234,8 @@
~~~~~~~~
`Template` contains connectivity settings that are pre-configured by Aether Operations.
-Templates are used to initialize `Slice` objects. `Template` has the following fields:
+Templates are used to initialize `Slice` objects, and are shared across Sites for an enterprise.
+`Template` has the following fields:
* `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is
the rule to use if no other rule in the Slice's application filter matches. `ALLOW-PUBLIC` is
@@ -227,7 +250,7 @@
Traffic-Class
~~~~~~~~~~~~~
-Specifies the class of traffic. Contains the following:
+Specifies the class of traffic, and is shared across Sites in an enterprise. Contains the following:
* `arp`. Allocation and Retention Priority.
* `qci`. QoS class identifier.
@@ -237,8 +260,8 @@
UPF
~~~
-Specifies the UPF that should forward packets. A UPF can only be used by one Slice at a time.
-Has the following fields:
+Specifies the UPF that should forward packets. The UPF is part of the Site object, and also can only be
+used by one Slice at a time. It has the following fields:
* `address`. Hostname or IP address of UPF.
* `port`. Port number of UPF.