API definitions

[andrewhowdencom]

• Under https://github.com/littlemanco/apis
• Implements https://github.com/littlemanco/www.littleman.co/issues/65
• An example unary, server stream and client stream stub

[andrewhowdencom]

Lifecycle:

• alpha
• beta
• stable/v1

Where APIs are deprecated

• Silent deprecation (conversion) (until next major version)
• Deprecation object (+1 version)
• Returning error with helpful status (+2 versions)
• Removal (+3 versions)

BC compatible changes do not result in API version bump (e.g. adding a field)

[andrewhowdencom]

Segmentation via user primitives would be interesting.

Smth like "is internal user" or "is beta user". Maybe from auth token? Unclear.

[andrewhowdencom]

Annotations (also follow the same life-cycle; if proto has advanced beyond lifecycle it has to progress from start with replicated calls)

• Proto → HTTP
• PII
• "Sensitive" (i.e. passwords); so does not end up in log files. https://github.com/protocolbuffers/protobuf/issues/1160

[andrewhowdencom]

Deprecation by degradation of service:

https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430/9

This is a brownout example, but other ones would be artificially spiking latency

[andrewhowdencom]

Operations should have SLOs associated. (Maybe a default SLO and then inherited? Unsure. But annotation for SLOs)

[andrewhowdencom]

Deprecate splitting messages and rpcs, keep them in the googleapis folder structure. For example,

ahsht.io
├── incident
│   └── v1
│       ├── incident.proto # RPC Definition, Incident messages
│       └── timeline.proto # Timeline messages
└── user
    └── v1alpha1
        └── user.proto # RPC Definition, user messages

Follows https://github.com/googleapis/googleapis

[andrewhowdencom]

Use "Any" for polymorphism.

[andrewhowdencom]

SLOs —

• Expressed as a time series (makes doing the math easier for the time series database)
• Defined as part of the API.
• Multiwindow, Multi burn rate by default.

SLOs on:

— Latency — Error Rate — Throughput? (this is tricky).

Should have a minimum and maximum bound; the max bound can be read by fault injection tooling to determine when to "inject chaos".

[andrewhowdencom]

https://github.com/ckaznocha/protoc-gen-lint https://github.com/nilslice/protolock

[andrewhowdencom]

APIs must be idempotent; systems should require little coordination.

Allows replaying of messages when data is corrupted or to sync systems (e.g. local node holding writes to "the cloud").

This means no post, basically.