README: comment out manifest ideas

README.md

@@ -5,13 +5,34 @@ Just a small experiment in replicating the API gateway pattern for microservices
 ## Manifest Format
 
 ```
+// service name, used in logging and metrics
 service printerfacts
+
+// https backend to reverse proxy to
 backend https://printerfacts.herokuapp.com
+
+// healthcheck endpoint. This should return 2xx.
 health /index.html
+
+// playbook URL for humans to use when responding to downtime
 playbook_url https://github.com/Xe/printerfacts/wiki/Playbooks#healthcheck-is-down
 
+// twirp blocks establish HTTP routes for both JSON and Protobuf twirp clients.
 twirp (
-  public v5 us.xeserv.api.Printerfacts Fact
+  // use assumptions for this service based on the twirp version in question.
+  require v5
+
+  // public <package> <service> <method>
+  // This defines a public API call. This also will require the application/json
+  // or application/protobuf Accept and Content-Type header with a POST verb
+  // where the path is built from the version assumptions + the twirp metadata.
+  public us.xeserv.api Printerfacts Fact
+  
+  // private <scope> <package> <service> <method>
+  // This defines a private API call scoped to users with the given permission
+  // for this service. This also will require the application/json or 
+  // application/protobuf Accept and Content-Type header with a POST verb where 
+  // the path is built from the version assumptions + the twirp metadata.
 )
 ```
 
@@ -20,9 +41,13 @@ service ponyapi
 backend https://ponyapi.apps.xeserv.us
 health /newest
 
-prefix /ponyapi
-
+// http blocks establish arbitrary http routes. For sanity and hygene reasons,
+// all services will have their routes prefixed by the service name. In this
+// example, the resulting routes on the API gateway would be `/ponyapi/all`, 
+// etc.
 http (
+  // public <method> <path>
+  public GET /
   public GET /all
   public GET /newest
   public GET /last_aired
@@ -31,6 +56,9 @@ http (
   public GET /random
   public GET /search
   
-  private root:admin GET /_stats
+  // private <scope> <method> <path>
+  private admin GET /_stats
 )
 ```
+
+