continue with instantiated a service docs

README.md

@@ -17,14 +17,14 @@ Sound good so far? Excellent! Let's start with basic, interactive usage of the s
 
 # Developer Guide
 
-This document is focused on usage and not extension of the application. Developers may be more interested in the
+This document is focused on usage and not extension of the application. Developers should read:
 
 - [development guide](docs/Customization.md)
 - [development error help](docs/CompileErrorHelp.md)
 
-The implementation and extension API is familiar to Scala service developers. To a large
-degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  A few of the niceties
-included:
+The implementation and extension API is familiar to Scala service developers. To a large degree,
+glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  A few of the
+niceties included:
 
 - Cluster is enabled and established without additional configuration.
 - Logging and data marshalling are configured appropriately.
@@ -126,6 +126,7 @@ $ curl http://localhost:10000/openapi.json
   "paths": {
     "/healthz": ...
     "/_ops/groups": ...
+    "/_ops/services": ...
 [...]
   }
 }
@@ -136,8 +137,10 @@ A brief overview:
 
 1. The `/healthz` route. We'll try that one below.
 2. The `/_ops/groups` route. This is an operations route for the groups in glngn server. All services
-are placed under a group. The default configuration does not include any groups (or services). This
+are placed under a group. The default configuration does not include any groups. This
 will be the first route we try in the `API Tour`.
+3. The `/_ops/services` route. This is an operations route to query the services that are available
+to instantiate under a group. This will be covered after the `/_ops/groups` route.
 
 ### Multiple Representations
 
@@ -191,10 +194,11 @@ The API conventions enforced by glngn server:
 - `/$GROUP/$SERVICE/...`
     - All other routes under a service are provided by a Service Fragment's `endpoints`
 
-#### Create a Group
+#### 1. Create a Group
 
-The `/_ops/groups` endpoint is used to query the existing groups and create new groups.
-All services are namespaced under a group. Before we can instantiate and use a service we must first create a group:
+The `/_ops/groups` endpoint is used to query the existing groups and create new groups.  All services
+are namespaced under a group. Before we can instantiate and use a service we must first create a
+group:
 
 ~~~
 $ curl --data '{ "id": "accounts", "name": "Client Accounts" }' localhost:10000/_ops/groups
@@ -221,7 +225,7 @@ $ curl localhost:10000/_ops/groups
     "id" : {
       "txt" : "accounts"
     },
-    "name" : "Cli Accounts",
+    "name" : "Client Accounts",
     "operators" : null
   }
 }
@@ -260,19 +264,84 @@ $ curl localhost:10000/openapi.json
 
 ##### Note: Groups Persist
 
-If you were to restart the `java -jar ./glngn-server-assembly.jar` process then you can
-note the group remains. `glngn-server` persists the created group to the provided state
-storage.
+If you were to restart the `java -jar ./glngn-server-assembly.jar` process note the group
+remains. `glngn-server` persists the created group to the provided state storage.
 
-In the example above the state storage is the `starter-state` directory provided to the 
+In the example above the state storage is the `starter-state` directory provided to the
 `--state-dir` option.
 
 #### Instantiate a Service Fragment
 
-TODO: show dynamic instantiation of a service fragment under a group
+Now that a group exists we will instantiate a service under that group. This will:
+
+1. Extend the API to include that service.
+2. Persist the data for that service under the group and service namespace.
+
+##### 1. Query for available services
+
+To determine what services fragments we can instantiate query the `/_ops/services` route:
+
+~~~
+
+$ curl localhost:10000/_ops/services.json
+[
+  "glngn.server.services.CounterService$"
+]
+~~~
+
+This provides the list of logical IDs of service fragments that can be instantiated under a group.
+This set can be customized using the developer SDK. We are using the default glngn distribution which
+includes a standard set of generic service fragments.
+
+##### 2. Instantiate the service fragment
+
+Let's pick the `glngn.server.services.CounterService$` service fragment to instantiate.
+
+After creating the group `accounts` a route was added `/accounts/_ops/services`. According to the
+OpenAPI spec this route accepts a `POST` of a `GroupServiceChange` json structure. The schema of
+this structure is:
+
+~~~
+"GroupServicesChange" : {
+    "required" : [
+        "serviceId",
+        "logicalServiceId"
+    ],
+    "type" : "object",
+    "properties" : {
+        "serviceId" : {
+            "type" : "string"
+        },
+        "logicalServiceId" : {
+            "type" : "string"
+        }
+    }
+}
+~~~
+
+We already know the logical service ID (`logicalServiceId`) from the query to `/_ops/services`. The
+`serviceId` is an identifier we can pick ourselves. We will pick `retail` for this example.
+
+~~~
+$ curl --data '{ "serviceId": "retail", \
+                 "logicalServiceId": "glngn.server.services.CounterService$" \
+               }' localhost:10000/accounts/_ops/services
+{
+  "retail" : [
+    "glngn.server.services.CounterService$"
+  ]
+}
+~~~
+
+Which replies with the new set of services under that group. This reply states the `retail` service
+is a composition of a list of service fragments. Which only contains
+`glngn.server.services.CounterService$` in this example.
 
 #### Use a Service
 
+With a service fragment instantiated under a group we can note the OpenAPI schema now includes routes
+for the `/accounts/retail` service:
+
 TODO:
 
 1. show dynamic instantiation of a service fragment in OpenAPI schema.