From programming languages to network protocols: lessons on API design

Lessons
on API design
Andrey Salomatin
@ﬂpvsk

API aﬀects
—What you can and can not do
—How does it perform
—How easy it is to make a mistake
2018-12-02 @ﬂpvsk @growitconf 3

Why look at well-known projects?
—To understand how the systems we use work
—To learn techniques we can apply in our projects
—To improve our thinking processes

1: A pixel
is not
a pixel2018-12-02 @ﬂpvsk @growitconf 5

Poor abstractions
limit what we can do
using the API.

x = ?
1. h1 / 2
2. (h1 - h2) / 2
3. (h1 + h2) / 2

x = ?
2. (h1 - h2) / 2

CSS
.container {
display: flex;
align-items: center;
}

x = ?
1. h3 * round(
(h1 - h2) / (2 * h3))
2. h3 * (h1 - h2) / 2
3. h3 * floor(
(h1 + h2) / 2)

x = ?
1. h3 * round(
(h1 - h2) / (2 * h3))

Center element within a grid
—CSS?
—iOS Auto Layout?
—Android Layout?

Vertical rhythm

Testing layout & paint
requires spinning oﬀ
a simulator or a browser

A pixel
is not
a pixel2018-12-02 @ﬂpvsk @growitconf 17

Browser vendors' in the early 90s:
—WWW is for documents
—Each browser will decide how to best display
pages to their users

Browser vendors' in the early 90s:
—WWW is for documents
—Each browser will decide how to display pages
—Seems like publishers want styling

…the style of a document
couldn't be designed
by either the author
or the reader
on their own…

…their wishes have to be
combined, or cascaded,
in some way.

Flutter design principles
—Layered API
—Access to Layout and Paint phases
—Full control over what is drawn on the screen

Vertical rhythm in Flutter
Offset getPositionForChild(
Size containerSize,
Size childSize
)

Vertical rhythm in Flutter
Offset getPositionForChild(
Size containerSize,
Size childSize
) {
final h1 = containerSize.height;
final h2 = childSize.height;
final h3 = rowHeight;
final rowsCount = ((h1 - h2) / (2 * h3)).round();
return Offset(0, rowsCount * h3);
}

Geometry
x = h3 * round(
(h1 - h2) / (2 * h3)
)

Properly layered API
gives freedom to build for
custom usecases.

2: Simple
or easy2018-12-02 @ﬂpvsk @growitconf 41

Programming language
designers balance
cognitive load
and capabilities.

Good abstractions
help API users
avoid mistakes.

Working with
concurrency

Concurrency basics in Java
synchronized method() {}
synchronized (object) {}
Object.wait();
Object.notify();
Object.notifyAll();

Actual concurrency in Java
—432 pages
—18cm x 3cm x 23cm
—635g
49

Correctness
is impossible
to enforce.

Concurrency basics in Rust

—New concept of Borrow Checker

—Thread safety enforced by the compiler

—Thread safety enforced by the compiler
—Custom primitives with Send and Sync traits

Expressive API
requires
more eﬀort
from the person
adopting it.

Choose what's important
and make it
hard to get wrong.

Other examples
—RPC (free for all) vs
REST (unification) vs
GraphQL (flexibility on the client)
—Ethereum Solidity (ffa) vs
Bamboo (understanding state & transitions)

3: Tree
that scales2018-12-02 @ﬂpvsk @growitconf 57

API is
a performance
bottleneck.

1h talk in Full-HD: 3.6GB
Chunk size Chunks count Metadata size
2MB 1800 >36KB
1MB 3516 >70KB
512KB 7032 >140KB

10h conference in Full-HD: 36GB
Chunk size Chunks count Metadata size
2MB 18000 >360KB
1MB 35160 >700KB
512KB 70320 >1.4MB

bittorent scaling issues
—Size of metadata
—Size of chunks

Dat protocol
Peer-to-peer
versioned
data sharing

Dat protocol
Decentralized
open-source
analog of Dropbox

Dat protocol
—Started as a way to exchange scientiﬁc data sets
—Growing as the protocol for p2p web
—Can be used to share TBs of dynamic data

Metadata size
—Bittorent: O(n)
—Dat: O(log(n))
n – number of chunks

API
is the ultimate
performance bottleneck

Other examples
—HTTP/1 and HTTP/2
—Bitcoin core and Lightning network

4: The only
const is
change2018-12-02 @ﬂpvsk @growitconf 91

Time and change are
API-designers'
worst nightmares.

REST API
POST '/:personId/posts'
PUT '/:personId/posts/:postId'
GET '/:personId/posts'

Creating new post
!
--> POST { text: 'All frameworks have tradeoffs!' } '/bob/posts'
"
<-- { id: 'post-1' }

Sharing post
!
--> POST { share: 'post-1', text: 'YES!!' } '/alice/posts'
"
<-- { id: 'post-2' }

Updating post
!
--> PUT { text: 'Serverless is a lie!' } '/bob/posts/post-1'
"
<-- { ok: true }

REST assumptions

REST assumptions
—Everything is a resource

REST assumptions
—Resources have unique identiﬁers

REST assumptions
—Resources have unique identiﬁers
—Resources can change over time*

Alternative
assumptions

Alternative assumptions

—Objects (facts) do not change over time

—Objects (facts) do not change over time
—References (labels) can change over time

The concepts of
time and change
are hard to get right.

Separate facts
from labels,
snapshots
from references.

Systems that get it right
—CouchDB, Datomic
—bittorent, Dat, IPFS
—Blockchain-based projects
—Event-sourcing-based projects

Summary

API design
is hard.

API aﬀects
—What you can and can not do
—How does it perform
—How easy it is to make a mistake

Learn good desgin
from systems
you use.

Listen to
code podcast.

THE END

From programming languages to network protocols: lessons on API design

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie From programming languages to network protocols: lessons on API design

Ähnlich wie From programming languages to network protocols: lessons on API design (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

From programming languages to network protocols: lessons on API design