Delivered at WS-REST 2015. This is a presentation for my submitted paper Rapido: A Sketching Web API Designers.

1. Rapido: A Sketching Tool
for Web API Designers
Ronnie Mitra
@mitraman
API Academy
CA Technologies

2. The Need for Good API Design
Goal Activity
Reduce cost of application
development
Improve API usability
Improve API adoption Improve API user experience

3. API Design: An Evolving Practice
focus on standards

4. API Design: An Evolving Practice
focus on standards focus on guidance

5. API Design: An Evolving Practice
focus on standards focus on guidance focus on process

6. Expert Guidance from Joshua Bloch
“
”Joshua Bloch

7. Adopt an External Perspective
Keep APIs free of
implementations details
“
”Joshua Bloch

8. Just Enough Functionality
When in doubt, leave it
out
“
”Joshua Bloch

9. One Chance to Get it Right
Public APIs, like
diamonds, are forever.
“
”Joshua Bloch

10. Three Common API Design Themes
1. Provide “just enough” functionality
2. User-centered design approach
3. Do not break existing applications with API changes

11. API Design Focus
1. Design for users (goal driven vs. exposure driven)
2. Evaluate interface for usability and experience measures
3. Make mistakes before implementation (iterate)

12. An Iterative User-Centred Design Approach
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement

13. Determine Value
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
revenue reach innovation
growth compliance intel

14. platform
language
organization
distance
knowledge
risk profile
investment
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Identify Users
Expertise
Goals
Familiarity

15. Ideate, Experiment, Sketch & Prototype
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement

16. Test Design Decisions
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement Lab Evaluation
Peer Evaluation
User Observation
Write Client Code
Participatory Design

17. Design Doesn’t Stop
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Analyze Real Usage
Identify Usability Bugs
Improve Functionality
Iterate and Evolve

18. Frank Gehry: Architect
An architect is
given a program,
budget, place,
and schedule.
Sometimes the
end product
rises to art
“
”

19. Architectural Models
Gehry Partners
Walt Disney
Concert Hall

20. Architectural Sketches
Frank Gehry
Walt Disney
Concert Hall

21. Architectural Sketches
Frank Gehry
Walt Disney
Concert Hall

22. Tool Supported Design
ShoP
Architects

23. Sketching in Film
Storyboard
Psycho
Alfred Hitchcock

24. Sketching in Sculpture
Maquette
The Burghers of Calais
Auguste Rodin

25. Bill Verplank on Sketching
“Sketches are an essential designer’s tool for capturing preliminary observations and
ideas. If they are fluent and flexible they support creativity. “
-- The Interaction Design Sketchbook, Bill Verplank

26. Bill Buxton on Sketching
Quick
Timely
Inexpensive
Disposable
Plentiful
Clear Vocabulary
Distinct Gesture
Minimal Detail

27. Low-Fideilty Prototype
High-Fideilty Prototype
Implementation
Sketch
Design Investment
Investment Iterations

28. Drawing: Benefits
Easy to get started
Cheap – low investment of
time
Freedom to experiment

29. Drawing: Limitations
Difficult to capture detail
and scale
Difficult to translate to
implementation
Lack of guidance

30. 45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class ApiProjectRouteController <
private
def find_project
@project = Project.find_by_n
render nothing: true, status
end
def find_todo
@todo = #...
end
#other finders also go here.
end
Writing Code: Benefits
Fits the problem space
Testable – immediate
evaluation
Easy to translate into
implementation

31. 45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class ApiProjectRouteController <
private
def find_project
@project = Project.find_by_n
render nothing: true, status
end
def find_todo
@todo = #...
end
#other finders also go here.
end
Writing Code: Limitations
Focus on the wrong
problems
Constrained by
language/framework
capability
Code investment may
reduce disposability

32. UML: Benefits
Purpose-built for design
and modeling
Incorporates drawn and
written design metaphors
Formal grammar, strong
tooling

33. UML: Limitations
Design teams must learn UML in
order to get started
UML is generic and is not specific to
API domain

34. RAML

35. Swagger

36. Blueprint

37. Description Language Editors: Benefits
API description domain is good
fit for design domain
High levels of usability – easy to
edit and design
Many editors offer mock
implementation – good for
evaluation

38. Description Language Editors: Limitations
Tied to specific language, user
must learn specification first
Specification language
constraints experimentation
Difficult to gain holistic
perspective of the design

39. Rápido!

40. Rapido: Goals
1. Support the API design sketching activity (unbundled
from general design tooling)
2. Reduce the cost of creating sketches (capture ideas
and improve disposability)
3. Improve integrability of sketches in design process

41. Rapido: Implementation
Node
MongoDB
EmberJS
Twitter Bootstrap
d3
API
SPA Backend

42. Rapido: Target Audience
User Goal: quickly design a web API
Required Knowledge:
• API Design fundamentals
• HTTP fundamentals
• CRUD pattern or Hypermedia type expertise

43. Rapido: Design Process
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export

44. Rapido: Design Process
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export
• Determine type of API :
(CRUD, Hypermedia)
• Determine media type :
(JSON, HAL, Collection+JSON)

45. Rapido: Vocabulary
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export
• Identify important
resources/components/activities
• Shared understanding
• Type-ahead list population in editor
• Promotes consistency

46. Rapido: Sketch
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export
• Visually design API
• Two modes: navigation and detail
• Low-fidelity modelling

47. Rapido: Sketch CRUD API
• Two views: navigation and
resource
• Tree model of resource
navigation
• Visual representation of
supported methods and URI
• Response bodies available in
resource view

48. Rapido: Sketch Hypermedia API
• Two views: navigation and state
• Graph of server response
navigation
• Visual representation of states
and transitions
• Response bodies available in
state view

49. Rapido: Evaluate
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export
• Review design

50. Rapido: Export
Create New Project
Define Vocabulary
Sketch API
Evaluate
Export
• Export sketch to other design tools
• Facilitates socialization and evaluation
• Facilitates prototype development

51. Rapido: Constraints
• HTTP headers can not be modeled
• No logic, conditional or error handling behaviour
• No query parameters

52. Rapido: Design Process
sketch protoype implement
Rapido Apiary JavaScript

53. Rapido: Alternative Design Process
sketch wireframe mock code
Drawing Rapido Apiary JavaScript

54. Rapido: Benefits
• Easy to draw navigation and structure of an API
• Allows designer to perceive the API conceptually
• Designed to support hypermedia types
• Integrates with higher fidelity tools (e.g. design tools
and API gateways)

55. Rapido: Limitations
• Too many constraints!
• Users want to model query parameters in CRUD
sketches
• Users want to model header data in all sketches
• Visualization problems
• Hypermedia sketches with many links to home fail
• Visualization becomes cluttered at high levels of
complexity

56. Rapido: Future
• Make available for general usage in June 2015
• Improve support for custom media type design
• Improve general usability and usefulness

57. Conclusions
• Designers should incorporate an iterative design
process to improve the quality of APIs
• Tooling can increase the efficiency of iterative design
processes
• Specialized tools like Rapido can be used within a
designer’s workflow to further aid the iterative
process

58. Rapido: A Sketching Tool
for Web API Designers
Ronnie Mitra
@mitraman
API Academy
CA Technologies