apig/README.md

# apig

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 (
  // 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.
)
```

```
service ponyapi
backend https://ponyapi.apps.xeserv.us
health /newest

// 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
  public GET /season/:snum
  public GET /season/:snum/episode/:enum
  public GET /random
  public GET /search
  
  // private <scope> <method> <path>
  private admin GET /_stats
)
```