SEBA-329 Reconcile API sections and make top level
Change-Id: Ia9f20a0c8c46c22646db72ec7ad2c1c4070d3db0
diff --git a/SUMMARY.md b/SUMMARY.md
index 2d52d4e..c9819fd 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -42,8 +42,6 @@
* [General Info](operating_cord/general.md)
* [GUI](operating_cord/gui.md)
* [Configuring the Service Graph](xos-gui/developer/service_graph.md)
- * [REST API](operating_cord/rest_apis.md)
- * [TOSCA](xos-tosca/README.md)
* [XOSSH](xos/dev/xossh.md)
* [XOS Internals](operating_cord/xos_internals.md)
* [XOS Containers](xos/xos_internals.md)
@@ -61,6 +59,10 @@
* [vRouter](vrouter/README.md)
* [AT&T Workflow Driver](att-workflow-driver/README.md)
* [Attach containers to external NICs](operating_cord/veth_intf.md)
+* [API Guide](api/api.md)
+ * [gRPC API Tutorial](xos/dev/grpc_api.md)
+ * [REST API](operating_cord/rest_apis.md)
+ * [TOSCA](xos-tosca/README.md)
* [Development Guide](developer/developer.md)
* [Getting the Source Code](developer/getting_the_code.md)
* [Writing Models and Synchronizers](xos/intro.md)
@@ -73,8 +75,6 @@
* [Core Models](xos/core_models.md)
* [Security Policies](xos/security_policies.md)
* [Tutorial](xos/tutorials/basic_synchronizer.md)
- * [API Interaction](api/api.md)
- * [gRPC API Tutorial](xos/dev/grpc_api.md)
* [Developer Workflows](developer/workflows.md)
* [Working on R-CORD Without an OLT/ONU](developer/configuration_rcord.md)
* [Building Docker Images](developer/imagebuilder.md)
diff --git a/api/api.md b/api/api.md
index 1f5574a..1948c3f 100644
--- a/api/api.md
+++ b/api/api.md
@@ -1,12 +1,14 @@
-# API Interaction
+# API Guide
This guide describes workflows for interacting with the API of the NEM. There
are several different API mechanisms that the NEM supports. Some of them are
used in a Northbound context, for services sitting on top the NEM to interact
with the NEM, and some are used internally for components to communicate with each other.
-* [gRPC](/xos/dev/grpc_api.md). The gRPC API is used internally for synchronizers and for Chameleon to speak with the XOS core. It's also available as a Northbound API.
-
-* REST. The REST API is implemented by the Chameleon container. In addition to being a popular Northbound API, it's also used by the XOS GUI.
-
-* Tosca. TOSCA is implemented by the xos-tosca container. TOSCA is used extensively in bootstrapping the system, and can also be used as a general-purpose runtime API.
+* [gRPC](/xos/dev/grpc_api.md). The gRPC API is used internally for synchronizers and for Chameleon to speak with the XOS core. It's also available as a Northbound API.
+
+* [REST](/operating_cord/rest_apis.md). The REST API is implemented by the Chameleon container. In addition to being a popular Northbound API, it's also used by the XOS GUI.
+
+* [TOSCA](/xos-tosca/README.md). TOSCA is implemented by the xos-tosca container and is typically used to configure and provision a
+ POD. Later sections of this guide give examples of TOSCA workflows used to provision and configure various
+ [profiles](/operating_cord/profiles.md) and [services](/operating_cord/services.md). TOSCA can also be used as a general-purpose runtime API.
diff --git a/operating_cord/general.md b/operating_cord/general.md
index 49a06ce..10a7ec4 100644
--- a/operating_cord/general.md
+++ b/operating_cord/general.md
@@ -1,15 +1,9 @@
# General Info
-CORD's operations and management interface is primarily defined by
-its Northbound API. There is typically more than one variant of this
-interface, and they are auto-generated from the models loaded into
-CORD, as described [elsewhere](../xos/README.md). Most notably:
+This section of the guide describes tools for interacting with CORD. These tools generally interact with
+CORD over a variety of APIs that are described [here](/api/api.md). Most notably:
* A graphical interface is documented [here](gui.md).
-* A RESTful version of this API is documented [here](rest_apis.md).
+* A text shell, [XOSSH](/xos/dev/xossh.md), can be used to operate on objects in the CORD data model.
-* A TOSCA version is typically used to configure and provision a
- POD. Later sections of this guide give examples of TOSCA workflows
- used to provision and configure various [profiles](profiles.md)
- and [services](services.md).