Practical API Design Ro Ronnie Mitra - - PowerPoint PPT Presentation

▶
practical api design
SMART_READER_LITE
LIVE PREVIEW

Practical API Design Ro Ronnie Mitra - - PowerPoint PPT Presentation

Jul 18, 2023 270 likes •887 views

June 2019 Practical API Design Ro Ronnie Mitra ronnie.mitra@publicissapient.com @mitraman 2 Publicis Sapient | Digital Business Transformation As a digital business transformation partner of choice, weve spent nearly three decades

slide-1
SLIDE 1

Practical API Design

June 2019

2

Ro Ronnie Mitra ronnie.mitra@publicissapient.com @mitraman

slide-2
SLIDE 2

Our scale Our clients Our scale Our clients Our scale Our clients Our scale Our clients Our scale Our clients Industry Recognition Serving you Serving you Serving you Serving you Serving you

Forrester Global Digital Business Transformation Accelerators – Q1 2019

Market presence* Stronger strategy Weaker strategy Weaker current

  • ffering

Stronger current

  • ffering

Challengers Contenders Strong performers Leaders DXC Technology Tata Consultancy Services Infosys Cognizant Atos Publicis Sapient Capgemini Accenture Wipro EY KPMG PwC McKinsey & Company IBM Deloitte

A startup mindset and agile methods to unlock value in ways that delight your customers and improve their operational effectiveness A transformation approach that is grounded in a view of both the company and the customer simultaneously A unique fusing of strategy and consulting, experience and engineering with an enduring culture of problem-solving creativity

20, 20,000 000

passionate people

50+ 50+

  • ffices globally connect

30 30

years of digital pioneering and customer innovation

20, 20,000 000

passionate people

50+ 50+

  • ffices globally connect

30 30

years of digital pioneering and customer innovation

20, 20,000 000

passionate people

50+ 50+

  • ffices globally connect

30 30

years of digital pioneering and customer innovation

20, 20,000 000

passionate people

50+ 50+

  • ffices globally connect

30 30

years of digital pioneering and customer innovation

20, 20,000 000

passionate people

50+ 50+

  • ffices globally connect

30 30

years of digital pioneering and customer innovation

Publicis Sapient | Digital Business Transformation

As a digital business transformation partner of choice, we’ve spent nearly three decades utilising the disruptive power of technology and ingenuity to help digitally enable our clients' business in their pursuit of next

slide-3
SLIDE 3

Ronnie Mitra

4

slide-4
SLIDE 4

The Scope of API Design

5

API Interface Model Implementation Instance Supporting Assets & Tools

slide-5
SLIDE 5

Significant API Design Costs

6

Interface Design Cost API Engineering Cost Client Engineering Cost Change Cost Safety Cost

After Publishing

slide-6
SLIDE 6

7 Practical Techniques For API Design

slide-7
SLIDE 7

Technique #1 Set The Right Design Goals

slide-8
SLIDE 8

Typical API Design Goals

9

Access to Data & Services

slide-9
SLIDE 9

Typical API Design Goals

10

Access to Data & Services Increased Developer Productivity Reduced Reliance on Staff Reduced Learning Time

slide-10
SLIDE 10

Typical API Design Goals

11

Access to Data & Services Increased Developer Productivity Reduced Reliance on Staff Increased Conversion Rate Reduced Learning Time Talent Retention Brand Credibility

slide-11
SLIDE 11

Typical API Design Goals

12

Access to Data & Services Increased Developer Productivity Reduced Reliance on Staff Increased Conversion Rate Reduced Learning Time Design costs increases as we move up Talent Retention Brand Credibility Functional Focus Usability Focus Experience Focus

slide-12
SLIDE 12

Calculating The Cost-Benefit of API Design

13

https://humanfactors.com/coolstuff/roi_increase_productivity.asp

slide-13
SLIDE 13

The Kano Model

14

user satisfaction feature implementation Performance Features (“known improvements”) Attractive Features (“delighters”) Basic Features (“tablestakes”)

slide-14
SLIDE 14

Invest in Attractive Features when API-X is a key success factor

15

user satisfaction Attractive Features (“delighters”) Increased Conversion Rates Brand Marketability Talent Retention

slide-15
SLIDE 15

Focus on Convention When API-X is not the priority

16

user satisfaction feature implementation Performance Features (“known improvements”) Attractive Features (“delighters”) Basic Features (“tablestakes”) Conventional Zone

slide-16
SLIDE 16

The Kano Model: Beware of Feature Degradation

17

user satisfaction feature implementation Performance Features (“known improvements”) Attractive Features (“delighters”) Basic Features (“tablestakes”)

slide-17
SLIDE 17

Use Imitation as a Shortcut to a Conventional API

Save time by using another API design as inspiration Co Considerations:

  • Who are the API’s users?
  • What domain does it operate in?
  • What is it like to use?

18

GET /changes GET /changes/watch

slide-18
SLIDE 18

Technique #2 Sketch & Prototype Iteratively

slide-19
SLIDE 19

Sketch & Prototype

20

Set Goal Research Sk Sketch Pr Prototype pe Build Publish

slide-20
SLIDE 20

Technique #3 Heuristic Evaluation

slide-21
SLIDE 21

API Design Reviews

Just like a code review, your API design can benefit from evaluation by other experts and your peers.

22

slide-22
SLIDE 22

API Design Reviews

Just like a code review, your API design can benefit from evaluation by other experts and your peers.

23

Pr Pract ctica cal Challenges:

  • Access to API design experts
  • Getting comprehensive feedback
  • Collating analysis from multiple experts
slide-23
SLIDE 23

Jakob Neilsen and Rolf Molich: 10 Usability Heuristics for User Interface Design

1. Visibility of System Status 2. Match Between System and the Real World 3. User Control and Freedom 4. Consistency and Standards 5. Error Prevention 6. Recognition rather than recall 7. Flexibility and Efficiency of Use 8. Aesthetic and Minimalist Design 9. Help Users Recognize, Diagnose, and Recover from Errors

  • 10. Help and Documentation

24

slide-24
SLIDE 24

7 Usability Heuristics for API Design

1. 1. Vi Visibility of System Status 2. 2. Ma Match Be Between Sy System and th the Re Real World User Control and Freedom 3. 3. Co Consistency and Standards 4. 4. Er Error

  • r Prevention
  • n

Recognition rather than recall 5. 5. Fl Flexibility and Efficien ency of Use Aesthetic and Minimalist Design 6. 6. He Help Us Users Recognize, Diagnose, and Recover from Er Error

  • rs

7. 7. He Help an and Do Documentation

25

slide-25
SLIDE 25

5 Usability Heuristics for Machine Interface Design

1. 1. Vi Visibility of System Status Ma Match Be Between Sy System and th the Re Real World User Control and Freedom 2. 2. Co Consistency and Standards 3. 3. Er Error

  • r Prevention
  • n

Recognition rather than recall 4. 4. Fl Flexibility and Efficien ency of Use Aesthetic and Minimalist Design 5. 5. He Help Us Users Recognize, Diagnose, and Recover from Er Error

  • rs

He Help an and Do Documentation

26

slide-26
SLIDE 26

5 Usability Heuristics for Machine Interface Design

1. 1. Vi Visibility of System Status 2. Consistency and Standards 3. Error Prevention 4. Flexibility and Efficiency of Use 5. Help Users Recognize, Diagnose, and Recover from Errors

27

Ho How eas easy is is it it to to un understand what is ha happening?

slide-27
SLIDE 27

5 Usability Heuristics for Machine Interface Design

1. Visibility of System Status 2. 2. Co Consistency and Standards 3. Error Prevention 4. Flexibility and Efficiency of Use 5. Help Users Recognize, Diagnose, and Recover from Errors

28

Ar Are interface and data models internally co consis iste tent? t? Do Does the API adhere to specifications and

  • r
  • rganizati

tion

  • nal sta

standards? s?

slide-28
SLIDE 28

5 Usability Heuristics for Machine Interface Design

1. Visibility of System Status 2. Consistency and Standards 3. 3. Er Error

  • r Prevention
  • n

4. Flexibility and Efficiency of Use 5. Help Users Recognize, Diagnose, and Recover from Errors

29

Ar Are the interface model and data model

  • v
  • verly complicated?

Is Is th there av avoi

  • idable ti

tight t cou

  • upling th

that t will ca cause errors when th thin ings ch change?

slide-29
SLIDE 29

5 Usability Heuristics for Machine Interface Design

1. Visibility of System Status 2. Consistency and Standards 3. Error Prevention 4. 4. Fl Flexibility and Efficien ency of Use 5. Help Users Recognize, Diagnose, and Recover from Errors

30

Do Does th the in inte terface ce mo model su suppor

  • rt bo

both begi beginner er an and d ad advan anced ed use e cas ases es? Ar Are th their ir op

  • pti

timizati tion

  • ns an

and d ac accel eler erat ators av available?

slide-30
SLIDE 30

1. Visibility of System Status 2. Consistency and Standards 3. Error Prevention 4. Flexibility and Efficiency of Use 5. 5. He Help Us Users Recognize, Diagnose, and Recover from Er Error

  • rs

Is Is er error in informatio tion ac accurat ate an and he helpful? Do Does it address both human and machine co conce cerns?

5 Usability Heuristics for Machine Interface Design

31

slide-31
SLIDE 31

Example of a Heuristic Analysis

32

REQUEST RESPONSE Vi Visi sibili lity:

  • “Use 202 instead”
  • “Provide a link where client can check job status

and add some info about job length” Co Consistency & St Standards:

  • “Use our standardized words for job status (“in-

progress”)”

slide-32
SLIDE 32

Find Usability Problems by Combining Results

33

Re Reviewer A

Re Reviewer B Re Reviewer C Re Reviewer D Visibility of System Status Consistency & Standards Error Prevention Flexibility & Efficiency of Use Help Users Recognize, Diagnose an Recover

slide-33
SLIDE 33

Technique #4 Write Code

slide-34
SLIDE 34

Technical Validation

Writing Code in the Design Phase

35

Machine Interface Model Proof of Concept API Implementation Iterative sketching

slide-35
SLIDE 35

Design Validation Technical Validation

Writing Code in the Design Phase

36

Machine Interface Model Proof of Concept API Implementation Proof of Concept Client Code Iterative sketching

slide-36
SLIDE 36

Technique: Write Code

37

“Code the use-cases against your API before you implement it, even before you specify it properly”

  • - Jo

Joshua B Blo loch

Photo Source: https://www.ideo.com/people/bill-moggridge https://github.com/jbloch

slide-37
SLIDE 37

Technique: Write Client Code

38

Write code from the perspective of your users early in the API design cycle.

slide-38
SLIDE 38

Tips for Using Client Code Effectively

39

Be Be yo your us user

Utilize languages, frameworks and techniques that you think your users would use.

Un Unit it tests aren’t ’t enough

Write code that accomplishes a goal from a user perspective – not code that tests a spec.

Fo Focus on insight not syntax

Don’t get caught investing too much time making code compile or worrying about code completeness.

slide-39
SLIDE 39

Technique #5 Participatory Design

slide-40
SLIDE 40

Participatory Design High Fidelity – Co-Design Team

42

Frontend Developer API Designer UX Designer Backend Developer Shipping Service Machine Interface Model

slide-41
SLIDE 41

Participatory Design Low Fidelity – Blank Paper Exercise

43

Frontend Developer Shipping Service Sketch Design the interface you want to use Shipping Service Machine Interface Model

slide-42
SLIDE 42

Technique #6 Choose a Style That Fits

slide-43
SLIDE 43

“REST” (The CRUD Style)

46

API

slide-44
SLIDE 44

“REST” (The CRUD Style)

47

API Shared understanding of data model Shared understanding of object address space Some RPC endpoints

slide-45
SLIDE 45

”REST” (The CRUD Style)

The API is a nested set of ”CRUD”able objects Interface design is “crafted” You design the objects, relationships and query model System

Client App

slide-46
SLIDE 46

”REST” (The CRUD Style): Cost Impacts

System Increases user learning costs (crafted API) Increases design costs (crafted API) Increases cost of future changes (coupling to data model and address space)

Client App

slide-47
SLIDE 47

”REST” (The CRUD Style): When I Like To Use It

When I want to deliver a conventional API experience When I need to provide an easily usable interface When I’m targeting client developers who are not in our team/organization System

Client App

slide-48
SLIDE 48

GraphQL (The Query Style)

API App Fixed RPC endpoint Shared Data Model

slide-49
SLIDE 49

GraphQL (The Query Style)

The API is a data source Interface design is standardized You design the data model and the RPC endpoints Schema System

Client App

slide-50
SLIDE 50

GraphQL (The Query Style): Cost Impacts

Schema System Increases learning costs (understand data model) Increases engineering costs (data pipe architecture) Increases cost of future changes (coupling to data model)

Client App

slide-51
SLIDE 51

GraphQL (The Query Style): When I Like To Use It

When the client developers are in in my team When my client developers need greater flexibility and autonomy When I want to present something new to my users Schema System

Client App

slide-52
SLIDE 52

API Styles – User Metaphors

55

Tunnel-RPC Style CRUD Style Hypermedia Style Event Driven Style Query Style

The API is a local library The API is a set of data objects The API is a website The API is a database The API is a notification message

slide-53
SLIDE 53

Technique #7 Make Practical Design Decisions

slide-54
SLIDE 54

Example

“What should we return when GET /songs?genre=classical doesn’t produce a match?”

57

slide-55
SLIDE 55

Resolving API Design Decisions

1.

  • 1. Ho

How re reversible is is th this is desig ign decis isio ion? If its easy to reverse we can afford to make a less optimal decision and improve it later. This is debt that is easy to pay back.

58

“Once we decide on this, it’s going to be difficult to change. We’d have to release a new version.”

slide-56
SLIDE 56

Resolving API Design Decisions

2. 2. Wha What do the he specifications and standards say? If there are clear rules, endeavor to follow them.

59

“We’ve read RFC 7231, now we are starting to think 404 is the way to go.”

slide-57
SLIDE 57

Resolving API Design Decisions

3. 3. Wha What would the he client code look like? Write client code to test your hypothesis and gain insight

60

“Actually, now it seems like a 200 with an empty collection makes the most sense!”

slide-58
SLIDE 58

Seven API Design Techniques

  • 1. Manage Your Debt
  • 2. Build a Conventional Product (when it makes sense)
  • 3. Perform Heuristic Evaluations
  • 4. Write Code
  • 5. Use Participatory Design
  • 6. Choose a style that fits
  • 7. Make Practical Design Decisions
slide-59
SLIDE 59

Bill Moggride on Design

62

“If there’s a simple, easy design principle that binds everything together, it’s probably about starting with the pe peopl ple”

Photo Source: https://www.ideo.com/people/bill-moggridge

slide-60
SLIDE 60

Practical API Design

June 2019

63

Ro Ronnie Mitra ronnie.mitra@publicissapient.com @mitraman