api design lessons learned: enterprise to startup€¦ · what? why? how? •a north star guides...
TRANSCRIPT
![Page 1: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/1.jpg)
API Design Lessons Learned: Enterprise to StartupMohamed [email protected]
![Page 2: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/2.jpg)
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
![Page 3: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/3.jpg)
E N T E R P R I S E V O I C E A I
_____________________WHATAREWEBUILDING?
![Page 4: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/4.jpg)
CAPABILITIES
AutomaticDial-in
Takes Interactive Commands
TranscribesKey Highlights
Indexed and Searchable Meetings
InteractiveMeeting
Dashboard
InteractiveWord Cloud
Share Meeting Highlights
HighlightReel
MeetingRecap Email
4
![Page 5: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/5.jpg)
LET’S TALK API DESIGN
![Page 6: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/6.jpg)
6
WHY API DESIGN MATTERS?
![Page 7: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/7.jpg)
7
BECAUSE BAD API DESIGN IS COSTLY!
![Page 8: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/8.jpg)
8
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC
Project1
Project 2
Project3
Project4
Project 5
Project6
Task1 Task2 Task3 Task4
TIMELINE WHEN API DESIGN IS GOOD
![Page 9: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/9.jpg)
9
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC
Project1
Project 2
Project3
Project4
Project 5
Project6
Task1 Task2 Task3 Task4
TIMELINE WHEN API DESIGN IS BAD
![Page 10: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/10.jpg)
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.
![Page 11: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/11.jpg)
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),
...
![Page 12: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/12.jpg)
12
LESSON 0: IMITATE THE GREAT (LEARN)
![Page 13: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/13.jpg)
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
![Page 14: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/14.jpg)
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
![Page 15: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/15.jpg)
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.
![Page 16: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/16.jpg)
LEARNING TO DODOING TO LEARN
16
![Page 17: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/17.jpg)
LET’S TALK CODE
![Page 18: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/18.jpg)
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
}
![Page 19: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/19.jpg)
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
![Page 20: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/20.jpg)
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)
}
![Page 21: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/21.jpg)
21
LESSON 1: FIND YOUR NORTH STAR
![Page 22: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/22.jpg)
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
![Page 23: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/23.jpg)
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
![Page 24: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/24.jpg)
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
![Page 25: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/25.jpg)
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
![Page 26: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/26.jpg)
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
![Page 27: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/27.jpg)
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
![Page 28: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/28.jpg)
EXAMPLE: LIFECYCLE OF A MICROSERVICE
28
5Scale on DC/OS
4Productionize (Go & Docker)
3Test the
hypothesis
2Deploy to
AWS (EC2)
1Prototype in
any language
![Page 29: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/29.jpg)
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
![Page 30: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/30.jpg)
30
LESSON2:DESIGNFORHUMANS
![Page 31: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/31.jpg)
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
![Page 32: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/32.jpg)
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
![Page 33: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/33.jpg)
PUT THE HUMAN FIRST!
33
If the human gets it,things will work quicker & better
Good API design is about communicating well to humans
![Page 34: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/34.jpg)
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
![Page 35: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/35.jpg)
EXAMPLE: PACKAGE ASSERT
35
// Java projects at LinkedIn are tested using TestNG, JUnit, & AssertJ:org.testng.Assert.assertEquals(x, y) // actual, expectedorg.junit.Assert.assertEquals(x, y) // expected, actual -> cognitive loadAssertions.assertThat(x).isEqualTo(y); // better
// Package assert* allows for easy & consist UT+DDT and test hook checksif !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")
![Page 36: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/36.jpg)
EXAMPLE: PACKAGE ASSERT
36
// Plays well with table-driven tests:cases := []struct {
id stringactual 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
![Page 37: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/37.jpg)
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()}
![Page 38: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/38.jpg)
ANOTHER EXAMPLE: API DESIGN PROCESS
38
Reiterate
5
Implement
4
WriteClientCode
3
Solicit&
DiscussFeedback
2
Spec
1
![Page 39: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/39.jpg)
FINALLY
![Page 40: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/40.jpg)
TAKEAWAYS: 3x3
40
LEARNING NORTH STAR PEOPLE FIRST
• See
• Do
• Teach
• Goals
• Tenets
• Methods
• Accelerate
• Communicate
• Empathize
![Page 41: API Design Lessons Learned: Enterprise to Startup€¦ · WHAT? WHY? HOW? •A north star guides your decision-making processes including API design choices. •In ever-changing environments,](https://reader033.vdocument.in/reader033/viewer/2022042302/5ecd8767ef1a830616765587/html5/thumbnails/41.jpg)
E N T E R P R I S E V O I C E A I
____________WE’REHIRING