Commit ee98ec7b authored by Corey O'Connor's avatar Corey O'Connor
Browse files

continue with instantiated a service docs

parent 05804c95
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment