Understanding the role of an API

  • Cars through the steering wheel and pedals
  • Restaurants through the menu
  • Toilets through a handy “push button” interface
  • Police through the telephone
  • Computers via a keyboard, mouse and the occasional profane word

What is an API?

What makes a “good” API”?


$ telnet google.com 80
Connected to google.com.
Escape character is '^]'.
GET /about/
HTTP/1.0 302 Found
Location: https://about.google/
Cache-Control: private
Content-Type: text/html; charset=UTF-8
... truncated for brevity ...Connection closed by foreign host.


  • TCP
  • ${REQUEST_VERB} - Something like "GET", "PUT", "POST", "HEAD" etc. Used to indicate whether to send, retrieve or inquire about data
  • ${URI} - The address of that data. Commonly, but not always modelled after the filesystem
  • ${HTTP_VERSION} - The HTTP protocol version
  • ${STATUS_CODE} - A numeric constant and text reference for the status of the request
  • ${HEADER_KEY}:${HEADER_VALUE} - Key / value pairs that hold request metadata
  • ${BODY} - The payload of data being sent either way


  • The network is reliable
  • Latency is zero
  • Repeatedly, until that delivery is acknowledged or
  • A single time, with no guarantee that the message was delivered at all
  • An upstream service being unavailable: HTTP will return the “503” service unavailable status code
  • The canonical service being unavailable: HTTP encourages (but does not require) timeout & retry
  • The upstream service fails: HTTP will return a “500” internal error status code
  • The upstream service is fine, but the request is bad: HTTP will return a 400 status code
  • The request is fine: HTTP will return a 200 status code.


Designing our own “good” APIs

Use an API specific DSL

  1. Documentation
  2. Wire format
  3. Error reporting
  4. Interchangability
  5. Language library generation

Understanding the domain

What is a heart rate?

  • A metric sampled over a fixed, standardized period
  • A count and average over an arbitrary period

How does the user identify themselves?

Modelling it

  1. Our user will attach a json web token (JWT) to the request that identifies who they are, and that can be verified against the authentication servers public key
  2. That JWT will contain a list of scopes that user is allowed to access
syntax = "proto3";package v1alpha1.types;import "google/protobuf/timestamp.proto";message HeartRateSample {    // When the sample started
google.protobuf.Timestamp start = 1;
// The length of time of the sample, expressed in seconds
float seconds = 2;
// The total number of heart beats in the sample
int32 beats = 3;
message HeartRateSampleList {
repeated HeartRateSample samples = 1;
syntax = "proto3";package v1alpha1.services;import "v1alpha1/types/heartrate.proto";
import "google/protobuf/empty.proto";
service HeartRateSampleService { // Push a single heart rate measurement to your profile
// Will overwrite other measurements started in the same second
rpc PutHeartRate(v1alpha1.types.HeartRateSample) returns (google.protobuf.Empty) {
// Put a list of heart rate measurements
rpc PutHeartRateList(v1alpha1.types.HeartRateSampleList) returns (google.protobuf.Empty) {
  1. Time series data is inherently time specific, and the API may as well express that rather than hide it
  2. Users will likely want to submit multiple samples in a single RPC call
  3. Users will likely be submitting their heart rate samples at a different time than they’re sampled, and thus need to embed that data in the RPC
  4. The RESTful methods are still a good model for managing this data

Take it slow

  • TCP was built after experience developing the PARC universal packet[13] and experience at ARPANET[14].
  • gRPC was developed with experience of developing stubby[15]
  • REST was designed based an examination of the properties of the web[16]



  • 3 month deprecation and removal period
  • No breaking changes without a version bump
  • A single version of backwards compatibility
  • An availability service level objective


  • A 12–24 month deprecation period
  • An availability guarantee

Be Unopinionated

  • The kubernetes “deployment” object embeds a copy of the “pod” object inside itself
  • Amazon Web Services allows users to build complex, user facing services on top of their APIs
  • Browser APIs allow users to create rich, interactive experiences without needing to understand browser internals

Be clear about failure

  • Bad data sent in by the user
  • Temporary conditions such as overload on a server
  • Fatal server conditions rendering a service unavailable
  • Network issues
  • HTTP Status codes
  • gRPC error codes
  • User facing errors
  • A code to reference the error. For example, “v1alpha1.foofield.length”
  • A human readable description of the error. For example, “The field FooField is longer than 10 characters”
  • A tip to try to address the issue directly. For example, “Try capping the length of the content in FooField”
  • A URL where the user might understand more about this particular class of errors. For example: “see e.api.bioprofile.co/v1alpha1.foofield.length”

In Conclusion


  1. T. Thwaites, “How I built a toaster — from scratch.” https://www.ted.com/talks/thomas_thwaites_how_i_built_a_toaster_from_scratch , Nov-2010.
  2. A. J. Jacobs, “My journey to thank all the people responsible for my morning coffee.” https://www.ted.com/talks/aj_jacobs_my_journey_to_thank_all_the_people_responsible_for_my_morning_coffee , Jun-2018.
  3. M. Andreessen, “Why software is eating the world.” https://a16z.com/2011/08/20/why-software-is-eating-the-world/ , Aug-2011.
  4. “Meatspace.” https://www.merriam-webster.com/words-at-play/what-is-meatspace .
  5. I. Grigorik, “A breif history of HTTP.” https://hpbn.co/brief-history-of-http/ , 2013.
  6. “Gopher (Protocol).” https://en.wikipedia.org/wiki/Gopher_(protocol) .
  7. C. Mims, “Inside the new industrial revolution.” https://www.wsj.com/articles/inside-the-new-industrial-revolution-1542040187 , Nov-2018.
  8. P. Deutsch, “The fallacies of distributed computing.” https://web.archive.org/web/20160909234753/https://blogs.oracle.com/jag/resource/Fallacies.html .
  9. “Message Delivery Reliability.” https://stackoverflow.com/questions/44204973/difference-between-exactly-once-and-at-least-once-guarantees .
  10. L. Torvaldis, “Re: [Regression w/ patch] Media commit causes user space to misbahave (was: Re: Linux 3.8-rc1) share.” https://lkml.org/lkml/2012/12/23/75 , Dec-2012.
  11. “API Design Guide.” https://cloud.google.com/apis/design/ , Apr-2019.
  12. “Protocol Buffers.” https://developers.google.com/protocol-buffers/ .
  13. “PARC Universal Packet.” https://en.wikipedia.org/wiki/PARC_Universal_Packet .
  14. NetworkT, “Which networking model came first: TCP/IP or OSI?” https://www.networkhunt.com/networking-model-came-first-tcp-ip-osi/ , Dec-2017.
  15. “Principles.” https://grpc.io/blog/principles/ .
  16. “Representational State Transfer.” https://en.wikipedia.org/wiki/Representational_state_transfer .
  17. R. T. Fielding, “Release Early, Release Often.” http://www.catb.org/ esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html , 2000.
  18. “Eating your own dogfood.” https://en.wikipedia.org/wiki/Eating_your_own_dog_food .



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store