Video and slides synchronized, mp3 and slide download available at URL http://bit.ly/2hAp0QN. Mohamed El-Geish explores lessons learned at big companies like Microsoft and LinkedIn, and adapts the insights drawn from them to fit a fast-growing startup. Filmed at qconnewyork.com. Mohamed El-Geish is Sr Director of Engineering at Workfit. He is passionate about empowering people around the world to communicate securely and effectively using online services that provide great experiences. Before joining Workfit, he worked at LinkedIn, working on feed personalization and relevance, and Microsoft, where he led a team of engineers working on email delivery for Outlook.com.

1. API Design Lessons Learned:
Enterprise to Startup
Mohamed El-Geish
g@workfit.io

2. InfoQ.com: News & Community Site
• 750,000 unique visitors/month
• Published in 4 languages (English, Chinese, Japanese and Brazilian
Portuguese)
• Post content from our QCon conferences
• News 15-20 / week
• Articles 3-4 / week
• Presentations (videos) 12-15 / week
• Interviews 2-3 / week
• Books 1 / month
Watch the video with slide
synchronization on InfoQ.com!
https://www.infoq.com/presentations/
startup-microsoft-linkedin

3. Presented at QCon New York
www.qconnewyork.com
Purpose of QCon
- to empower software development by facilitating the spread of
knowledge and innovation
Strategy
- practitioner-driven conference designed for YOU: influencers of
change and innovation in your teams
- speakers and topics driving the evolution and innovation
- connecting and catalyzing the influencers and innovators
Highlights
- attended by more than 12,000 delegates since 2007
- held in 9 cities worldwide

4. 2
4 This presentation may
contain content that
contradicts how your
company designs APIs
4 Startups are nimble and
daring; don’t try this at
home work (or do try it)!
4 YMMV
WARNING

5. E N T E R P R I S E V O I C E A I
_____________________
WHAT ARE WE BUILDING?

6. CAPABILITIES
Automatic
Dial-in
Takes Interactive
Commands
Transcribes
Key Highlights
Indexed and
Searchable
Meetings
Interactive
Meeting
Dashboard
Interactive
Word Cloud
Share Meeting
Highlights
Highlight
Reel
Meeting
Recap Email
4

7. LET’S TALK API DESIGN

8. 6
WHY API DESIGN
MATTERS?

9. 7
BECAUSE BAD API DESIGN IS COSTLY!

10. 8
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC
Project 1
Project 2
Project 3
Project 4
Project 5
Project 6
Task 1 Task 2 Task 3 Task 4
TIMELINE WHEN API DESIGN IS GOOD

11. 9
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC
Project 1
Project 2
Project 3
Project 4
Project 5
Project 6
Task 1 Task 2 Task 3 Task 4
TIMELINE WHEN API DESIGN IS BAD

12. EXAMPLE: A TALE OF TWO QUEUES
10
// We used to use a FIFO SQS queue to send messages:
request, _ := q.SendMessageRequest(&sqs.SendMessageInput{
QueueUrl: aws.String(queueURL),
MessageBody: aws.String(messageBody),
MessageGroupId: aws.String(groupID),
MessageDeduplicationId: aws.String(dedupeID),
})
return request.Send()
// Then we switched that code to use a standard (non-FIFO) queue.
// Expectation: The API clearly denotes a FIFO-specific interface.

13. EXAMPLE: A TALE OF TWO QUEUES
11
// Reality: latent errors due to ambiguous API overloading;
// we can’t use the last two arguments for standard queues!
// This parameter applies only to FIFO (first-in-first-out) queues.
// ... [many lines later] ...
// MessageGroupId is required for FIFO queues.
// You can't use it for Standard queues.
// One way to mitigate this is to create a FIFO-specific API:
request, _ := q.SendFIFOMessageRequest(&sqs.SendFIFOMessageInput{
MessageGroupId: aws.String(groupID),
MessageDeduplicationId: aws.String(dedupeID),
...

14. 12
LESSON 0: IMITATE THE GREAT (LEARN)

15. PERCEPTUAL LEARNING
• Study: Non-pilots did better than
experienced pilots; PL works for other
complex fields.*
• Cognitive Science: PL accelerates gaining
expertise via pattern recognition.**
• SMDMTM: See one many; do one many;
teach one many — we require many high-
quality examples for high SNR.***
13

16. 14
1 Ample time and resources
2 Scrutinized processes and reviews
3 Access to a ton of code and designs
4 Formal coaching and training
5 Abundance of talent and expertise
BIG COMPANIES = GREAT FOR LEARNING

17. 15
LEARNING AS A TENET
THE WORKFIT WAY
4Humans are the most important
factor in the success of
software.
4We learn to make new mistakes.
4We invest in learning and
coaching: long-term ROI.
4Accelerated learning =>
high iteration velocity.

18. LEARNING TO DO
DOING TO LEARN
16

19. LET’S TALK CODE

20. EXAMPLE: PACKAGE MUST
18
// We noticed a pattern when declaring main package variables
// We also noticed a pattern in Go’s standard library:
// MustCompile is like Compile but panics if the expression cannot be
// parsed. It simplifies safe initialization of global variables holding
// compiled regular expressions.
func MustCompile(str string) *Regexp {
regexp, error := Compile(str)
if error != nil {
panic(`regexp: Compile(` + quote(str) + `): ` + error.Error())
}
return regexp
}

21. EXAMPLE: PACKAGE MUST
19
// So we imitated the same pattern into package must:
// CreateMeetingsClient wraps fabric.NewMeetingsClient
// with default parameters.
func CreateMeetingsClient() fabric.MeetingsClient {
client, err := fabric.NewMeetingsClient(
context.TODO(), fabric.DefaultClientConfig)
if err != nil {
reportPanic(err)
}
return client
}
var meetingsClient = must.CreateMeetingsClient() // how it’s called

22. ANOTHER EXAMPLE: PACKAGE ERRORS
20
// Visual Studio TFS errors have IDs to reference them in docs*;
// free-form errors are hard to map into a single TSG/failure mode;
// our errors package allows for consistency, reuse, strong contracts,
// brevity, testability, error handling hooks, and localizability.
const wf11200 = `WF11200: HTTP response status code was not 2xx`
// WF11200 occurs when an HTTP response has a status code other than 2xx.
func WF11200(response interface{}) error {
log.Error(wf11200, "response", response)
return newError(wf11200)
}

23. 21
LESSON 1: FIND
YOUR NORTH STAR

24. 22
“As to the methods there may be a million
and then some, but principles are few. The
man who grasps principles can successfully
select his own methods. The man who tries
methods, ignoring principles, is sure to
have trouble.”
RALPH WALDO EMERSON

25. WHAT? WHY? HOW?
• A north star guides your decision-making
processes including API design choices.
• In ever-changing environments, one can
get lost and distracted by myopic goals.
• Align design goals with business goals;
we don’t design in a vacuum.
• Find your treasure and guard it well.
23

26. KEY CHALLENGES STARTUPS
& NEW PROJECTS FACE
• A blank canvas: an overwhelming number of
decisions to make -> decision fatigue.
• Velocity is life; grow fast or die slow:
“If a software company grows at [20%
annually], it has a 92 percent chance of
ceasing to exist within a few years.”*
• Security: it’s inconvenient; it’s everyone’s
responsibility; and it can slow us down.
24

27. 25
SETTING GOALS & GUIDING PRINCIPLES
4Scope: short- vs. long- term.
4Agreeing on guiding principles ->
a decision-making framework ->
conflict-resolution mechanism.
4We strive to foster wisdom and
autonomy.
THE WORKFIT WAY

28. GOALS AND GUIDING PRINCIPLES
• Short-term: security, correctness, iteration velocity, availability,
performance, throughput, scalability, and maintainability.
• Long-term: security, correctness, availability, throughput, performance,
scalability, maintainability, and iteration velocity.
• Balance: Design with scalability and maintainability in mind; trade off only
when necessary.
• Methods: encryption, ACLs, cyber hygiene, CI, testing, SOA, A/B testing,
tracking and telemetry, KISS, etc.
26

29. SHORT-TERM GUIDING PRINCIPLES IN ACTION
• Data Formats: Binary or textual?
• Contracts: Whether or not to enforce schemas?
• Programming Languages: Why Go, C++, Python, and Java?
• Investing in CI: Travis, Docker, and DC/OS.
• Rich Logging: verbose and structured; multi-engine; and secure.
27

30. EXAMPLE: LIFECYCLE OF A MICROSERVICE
28
5
Scale on
DC/OS
4
Productionize
(Go & Docker)
3
Test the
hypothesis
2
Deploy to
AWS (EC2)
1
Prototype in
any language

31. LET’S TALK MORE ABOUT CHALLENGES
• Latent conflict of priorities: Go is great but it had its issues (e.g. ICS parser).
• Building for scale: balancing TTM with future projections of scalability.
• Susceptibility to tribal knowledge syndrome: how to share knowledge & move fast?
e.g., log.Error(wf11200, "response", response) // what’s "response"?
• Many choices: green-field projects with high degrees of freedom; e.g., we moved
from Kubernetes to DC/OS because of:
– Better support of security and stateful solutions
– Stability (on AWS)
– GPU Time-sharing
29

32. 30
LESSON 2: DESIGN FOR HUMANS

33. LEARN ABOUT ALL SORTS OF
DESIGN
• Good API design qualities transcend
code.
• Industrial design cares about interfacing
with a physical product.
• User-centered design focuses on
usability.
• Many analogies to draw among all sorts
of design.
31

34. TEN PRINCIPLES OF GOOD DESIGN BY DIETER RAMS
32
1 Good Design Is Innovative
2 Good Design Is Useful
3 Good Design Is Aesthetic
4 Good Design Is Understandable
5 Good Design Is Unobtrusive
6 Good Design Is Honest
7 Good Design Is Long-lasting
8 Good Design Is Thorough
9 Good Design Is Eco-friendly
10 Good Design Is Minimal

35. PUT THE HUMAN FIRST!
33
If the human gets it,
things will work quicker & better
Good API design is about
communicating well to humans

36. 34
“Let us change our traditional attitude to
the construction of programs: Instead of
imagining that our main task is to instruct
a computer what to do, let us concentrate
rather on explaining to human beings what
we want a computer to do.”
DONALD KNUTH

37. EXAMPLE: PACKAGE ASSERT
35
// Java projects at LinkedIn are tested using TestNG, JUnit, & AssertJ:
org.testng.Assert.assertEquals(x, y) // actual, expected
org.junit.Assert.assertEquals(x, y) // expected, actual -> cognitive load
Assertions.assertThat(x).isEqualTo(y); // better
// Package assert* allows for easy & consist UT+DDT and test hook checks
if !assert.For(t).ThatActual(x).Equals(y).Passed() {
analyze(x, y)
}
assert.For(t).ThatActual(x).Equals(expected).ThenRunOnFail(analyze)
assert.For(t).ThatActual(x).Equals(expected).ThenDiffOnFail()
assert.For(t).ThatCalling(someFunc).PanicsReporting("error")

38. EXAMPLE: PACKAGE ASSERT
36
// Plays well with table-driven tests:
cases := []struct {
id string
actual interface{}
expected interface{}
}{
{"different values", 42, 13},
// ...
}
for _, c := range cases {
assert.For(t, c.id).ThatActual(c.actual).Equals(c.expected)
} // prints test case ID in failure messages

39. EXAMPLE: PACKAGE ASSERT
37
// At Microsoft, we used the internal access modifier and friend
// assemblies for testability; at LinkedIn we used package-private
// methods and documented that they are @VisibleForTesting; at Workfit,
// using tags, instead of comments, enables us to check test hooks:
type sleeper struct {
sleep func(time.Duration) `test-hook:"verify-unexported"`
}
// What gets exposed for testability shall not be exported!
func TestHooksAreHidden(t *testing.T) {
assert.For(t).ThatType(reflect.TypeOf(sleeper{})).HidesTestHooks()
}

40. ANOTHER EXAMPLE: API DESIGN PROCESS
38
Reiterate
5
Implement
4
Write
Client
Code
3
Solicit
&
Discuss
Feedback
2
Spec
1

41. FINALLY

42. TAKEAWAYS: 3x3
40
LEARNING NORTH STAR PEOPLE FIRST
• See
• Do
• Teach
• Goals
• Tenets
• Methods
• Accelerate
• Communicate
• Empathize

43. E N T E R P R I S E V O I C E A I
____________
WE’RE HIRING

44. @elgeish
g@workfit.io
www.elgeish.com
linkedin.com/in/elgeish
CONTACT INFO
42

45. Watch the video with slide
synchronization on InfoQ.com!
https://www.infoq.com/presentations/
startup-microsoft-linkedin