fix: get end-to-end CRUD journey, fix grpc (#20)

The example server new supports an end-to-end
CRUD flow of creating, reading, updating, and
deleting a resource.

This serves as a great illustrative example of 
a resource-oriented API as well as validating 
the function of the test server.

grpc gateway integration was also broken when
the generated file structure was changed, so that
is now fixed.

also fixing tests by making field order idempotent.

.github/workflows/test.yml

@@ -19,11 +19,15 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v2
 
-      - name: Verify no change to generated files.
+      - name: "test: no change to generated files."
         run: |
           go install github.com/bufbuild/buf/cmd/[email protected]
           ./scripts/verify-goldens.sh
 
+      - name: "test: example server function"
+        run: |
+          ./scripts/test_http_api.sh
+
       # - name: Run script
       #   run: |
       #     ./scripts/run-api-linter.sh

README.md

@@ -12,15 +12,29 @@ aepc works off of an internal "hub" representation of a resource, while each of
 
 ```mermaid
 flowchart LR
-    hub("unified service and resource hub")
-    protoResources("proto messages")
+    hub("aepc: unified service and resource hub")
+    resources("AEP Resource Definitions")
     proto("protobuf")
-    crd("Custom Resource Definitions (K8S)")
-    http("HTTP REST APIs")
-    protoResources --> hub
+    crd("Kubernetes Custom Resource Definitions and operators (planned)")
+    http_planned("HTTP Rest APIs (planned)")
+    http("HTTP REST APIs via gRPC-gateway")
+    openapi("OpenAPI Schema")
+    terraform("Fully Generated Terraform Provider")
+    cli("command-line interface (planned)")
+    docs("API documentation (planned)")
+    sdks("Language-specific libraries (planned)")
+    ui("interactive website to create, edit, list, and modify resources (planned)")
+    resources --> hub
     hub  --> proto
-    hub  --> http
-    hub  --> crd
+    hub  --> openapi
+    hub  --> http_planned
+    proto --> http
+    http --> terraform
+    http --> cli
+    http --> crd
+    openapi --> docs
+    openapi --> sdks
+    openapi --> ui
 ```
 
 ## User Guide

example/README.md

@@ -11,24 +11,6 @@ To start the service, running the following from the root directory:
 go run example/main.go
 ```
 
-## Architecture
-
-```mermaid
-graph TD
-    resource("resource definitions in bookstore.yaml")
-    serviceProto("fully defined service in bookstore.yaml.output.proto")
-    gService("gRPC service")
-    httpService("HTTP -> gRPC gateway")
-    OpenAPI("OpenAPI Definition")
-    client("Client")
-    resource -- aepc --> serviceProto
-    resource -- aepc --> OpenAPI
-    serviceProto -- protoc --> gService
-    serviceProto -- protoc --> httpService
-    OpenAPI -- terraform-provider-openapi --> terraform provider
-    OpenAPI -- openapi-generator et al --> clients
-```
-
 ## Terraform Provider
 
 This example provides an example of generating a terraform provider using
@@ -66,4 +48,8 @@ $ terraform apply -auto-approve
 # - comment the resource out
 $ terraform apply -auto-approve
 # - observe the resource has been deleted.
-```
+```
+
+### API Example
+
+See [test_http_api.sh](./scripts/test_http_api.sh).

example/bookstore/v1/bookstore.proto

@@ -34,7 +34,7 @@ service Bookstore {
 
   // An aep-compliant Update method for Book.
   rpc UpdateBook ( UpdateBookRequest ) returns ( Book ) {
-    option (google.api.http) = { patch: "/{book.path=books/*}", body: "book" };
+    option (google.api.http) = { patch: "/{path=books/*}", body: "book" };
 
     option (google.api.method_signature) = "book,update_mask";
   }
@@ -61,12 +61,6 @@ service Bookstore {
 
 // A Book resource.
 message Book {
-  // Field for id.
-  string id = 10001;
-
-  // Field for edition.
-  int32 edition = 4;
-
   // Field for isbn.
   string isbn = 1;
 
@@ -76,8 +70,14 @@ message Book {
   // Field for published.
   bool published = 3;
 
+  // Field for edition.
+  int32 edition = 4;
+
   // Field for path.
   string path = 10000;
+
+  // Field for id.
+  string id = 10001;
 }
 
 // A Create request for a  Book resource.