DESIGN & DEPLOY
A DATA-DRIVEN API IN 2 HOURS

All-in-one platform for Web APIs
http://apispark.com

Restlet undersigned th...
PRESENTER
ENTREPRENEUR AND WEB API EXPERT
Jérôme LOUVEL







CEO of Restlet
12 years of experience in software (EU...
AGENDA
 Part 1 – API design
– Info: The ROA/D to API design
– Lab: Specify your Pizza API

 Pause
 Part 2 – API deploym...
Info : The ROA/D to API design

PART 1 - API DESIGN (15’)
HOW TO DESIGN MY API?
 Let’s pick up a web API framework and prototype!
 I’ll read and digest REST dissertation first

...
METHODOLOGY
 Resource-Oriented Analysis & Design
– Based on our consulting experience at Restlet
– Variant of OOA/D descr...
ITERATION STEPS

Requirements
gathering

Implementation
testing

Design
implementation

Requirements
analysis

Solution
de...
PROJECT PHASES
 Each phase contains
– Several iterations
– More requirements & analysis in early phases
– More implementa...
&
UX Design for API Developers
Requirements
gathering

• UX != UI  UXD != API
• Similar process:
– User research  Person...
DESCRIBE API PERSONAS
• Bart is a Mobile app
developer
–
–
–
–

Unreliable networks
Pre-fetch and cache data
Small data pa...
DESCRIBE API FEATURES
• Use cases for Bart
– Build an iPad app version
– Build an Android app version
– Build an iPhone ap...
BALANCE API FEATURES
SIMPLICITY VS CAPABILITY
Complexity
Powerful but
unusable

Adding
features

Your web API
sweet spot

...
&
Domain-Driven Design for API Developers
Requirements
analysis

• When your domain isn’t trivial
• Key building blocks
– ...
IDENTIFY DOMAIN ENTITIES
Advises
Customer

• Defined by thread
of continuity
Invoice
Order

• Has own identity

?

• Not d...
DESCRIBE DOMAIN ENTITIES
Advises

Customer
id : String
name : String
created : Date
modified : Date

• Describe
properties...
Next design steps are more API specific
Requirements
analysis

• Define your logical architecture
– Learn about Netflix AP...
LOGICAL ARCHITECTURE

UI

API resources

Domain objects

Data tables

_

+
Reusable
DERIVING THE DOMAIN MODEL

Domain
entities

ROA/D

API
resources

ROM

OOA/D

Domain
objects

IDEF1

ORM

Data
tables
IDENTIFY YOUR APIS
Advises
Browser
Connected
mobile devices

Smart
environnement

• Driven by personas

Pages + API

• Eac...
DESCRIBE API RESOURCES
Advises

Root
http://localhost:8111/
GET() : xml | json | html

• Driven by use
cases

1
Accounts
1...
Lab : Specify your Pizza API

PART 1 - API DESIGN (50’)
&

Requirements
gathering

Requirements
analysis
DESCRIBE PIZZA API PERSONAS
Instructions
• Contextual and
specific to your API
• Don’t denature a
persona
• Describe a tot...
DESCRIBE PIZZA API USE CASES
Instructions
•

Put your persona in
context with use cases
and derive features

•

Describe a...
&

Requirements
analysis

Solution
design
DESCRIBE DOMAIN ENTITIES
Advises
• List 4 entities
• Describe their
properties
• Including
relationships
• Time limit: 10’
IDENTIFY YOUR APIS
Advises
• Driven by personas
and features

• Describe 2 endpoints
(1 for each API)
• Several APIs shoul...
DESCRIBE API RESOURCES
Advises
• Driven by use cases

• Derived from
Domain Entities
• Single and
collection resources
• T...
Solution
design

Next steps are about API deployment
• Implement the Domain Entities
– As a persistent store

• Implement ...
TIME FOR A BREAK ! (10’)
Info : APISpark as an IDE and runtime

PART 2 - API DEPLOYMENT (5’)
WEB API PROJECT
TYPICAL LIFE CYCLE

1) Do It Yourself (DIY)
long, risky, expensive but highly flexible

Create

Host

Mana...
APISPARK PLATFORM
CURRENTLY IN RESTRICTED PUBLIC BETA

Send us your feed-back
and help us making it the
best PaaS for Web ...
COMPOSING APISPARK CELLS

Java

iOS

HTTP

JS

HTTP

Custom API

Entity Store

File Store
STRUCTURE OF WEB APIS

HTTP

HTTPS

API Contract
Web API
template
Complete
web API

Implementation

Runtime
Lab : Deploy your Pizza API

PART 2 - API DEPLOYMENT (35’)
SOCIAL LOGIN
YOUR DASHBOARD
ENTITY STORE CREATION
ENTITY PROPERTIES
WEB API CREATION
API GENERATION FROM ENTITY STORE
API DEPLOYMENT
CLIENT SDK GENERATION
Next steps are about closing the API loop
Design
implementation

• Verify that the API works as
expected
– Manual tests
– ...
API TESTING WITH HTTP CLIENT
BUILT-IN ANALYTICS
CONCLUSION
 Designing a web API requires thinking
– The UX of developers using your API matters
– Use a minimal but effec...
KEEP IN TOUCH!

http://apispark.com
http://blog.restlet.com
Twitter: @apispark
jlouvel@restlet.com

Restlet undersigned th...
Upcoming SlideShare
Loading in...5
×

Design & Deploy a data-driven Web API in 2 hours

1,594

Published on

Learn how to use the ROA/D process along with UX and DDD to design a proper web API, then learn how APISpark platform (PaaS) compares to a DIY approaches.

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,594
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
22
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Design & Deploy a data-driven Web API in 2 hours

  1. 1. DESIGN & DEPLOY A DATA-DRIVEN API IN 2 HOURS All-in-one platform for Web APIs http://apispark.com Restlet undersigned this GigaOM research report, written by Kin Lane October 23, 2013
  2. 2. PRESENTER ENTREPRENEUR AND WEB API EXPERT Jérôme LOUVEL       CEO of Restlet 12 years of experience in software (EU and US) Restlet Framework creator (2005) JAX-RS 1.0 expert (JSR-311) Contributor to “RESTful Web Services” (O’Reilly) Co-author of “Restlet in Action” (Manning) Contact  jlouvel@restlet.com  Twitter : @jlouvel and Google+  Blog : blog.restlet.com
  3. 3. AGENDA  Part 1 – API design – Info: The ROA/D to API design – Lab: Specify your Pizza API  Pause  Part 2 – API deployment – Info: APISpark as an IDE and runtime – Lab: Deploy your Pizza API
  4. 4. Info : The ROA/D to API design PART 1 - API DESIGN (15’)
  5. 5. HOW TO DESIGN MY API?  Let’s pick up a web API framework and prototype!  I’ll read and digest REST dissertation first  APIs are lighter Web Services, nothing new  Let’s look at popular APIs and follow best practices  My API should have nice URIs and CRUD methods  Which kind of design process should I follow?  Many ways to tackle this…
  6. 6. METHODOLOGY  Resource-Oriented Analysis & Design – Based on our consulting experience at Restlet – Variant of OOA/D described in « Restlet in Action » book – Usable on Agile projects and with Lean approaches Learn about the ROA/D methodology !
  7. 7. ITERATION STEPS Requirements gathering Implementation testing Design implementation Requirements analysis Solution design
  8. 8. PROJECT PHASES  Each phase contains – Several iterations – More requirements & analysis in early phases – More implementation & testing in later phases Inception Elaboration Construction Transition
  9. 9. & UX Design for API Developers Requirements gathering • UX != UI  UXD != API • Similar process: – User research  Persona  Use case  Feature(s) • Enrich ROA/D during – Requirements – Analysis Requirements analysis • Based on Nazmul and Izabel Idris workshop for Google I/O 13 – http://bit.ly/uxcommunity – Adapted to web APIs by APISpark with help of SFEIR
  10. 10. DESCRIBE API PERSONAS • Bart is a Mobile app developer – – – – Unreliable networks Pre-fetch and cache data Small data packets best Android first, then iPhone • Homer is a HTML 5 developer – – – – Good connectivity Bigger data for larger screens Same-Origin Policy Works with AngularJS Advises • Contextual and specific to your API • Don’t denature a persona • Don’t support too many personas • Think about game consoles, connected TV / cars, glue scripts
  11. 11. DESCRIBE API FEATURES • Use cases for Bart – Build an iPad app version – Build an Android app version – Build an iPhone app version • Features – – – – Provide an iOS client SDK Provide an Android client SDK Supported GZip HTTP Monitor API traffic per mobile device type Advises • Identify use cases per persona • Derive features from concrete use cases • Be careful about feature creep!
  12. 12. BALANCE API FEATURES SIMPLICITY VS CAPABILITY Complexity Powerful but unusable Adding features Your web API sweet spot Bad UX design Good UX design Simplistic and frustrating Capability Adding features
  13. 13. & Domain-Driven Design for API Developers Requirements analysis • When your domain isn’t trivial • Key building blocks – Entity – Service – Repository • Enrich ROA/D during Solution design – Analysis – Design • Based on Eric Evans book
  14. 14. IDENTIFY DOMAIN ENTITIES Advises Customer • Defined by thread of continuity Invoice Order • Has own identity ? • Not defined by its properties ( value objects)
  15. 15. DESCRIBE DOMAIN ENTITIES Advises Customer id : String name : String created : Date modified : Date • Describe properties 1 * Invoice id : String amount : Integer iterms : List<InvoiceItem> modified : Date * Order id : String amount : Integer iterms : List<OrderItem> modified : Date • Describe relationships • Use class diagrams
  16. 16. Next design steps are more API specific Requirements analysis • Define your logical architecture – Learn about Netflix API strategy • Derive your domain entities into – API resources – Domain objects – Data tables Solution design • Design your API resources – URI templates – Representations structure – Supported HTTP methods
  17. 17. LOGICAL ARCHITECTURE UI API resources Domain objects Data tables _ + Reusable
  18. 18. DERIVING THE DOMAIN MODEL Domain entities ROA/D API resources ROM OOA/D Domain objects IDEF1 ORM Data tables
  19. 19. IDENTIFY YOUR APIS Advises Browser Connected mobile devices Smart environnement • Driven by personas Pages + API • Each persona might need a specific API Domain Model Partner Internal IS • All APIs should share the same domain model
  20. 20. DESCRIBE API RESOURCES Advises Root http://localhost:8111/ GET() : xml | json | html • Driven by use cases 1 Accounts 1 accounts/ • Derived from Domain Entities GET() : xml | json | html POST(xml | json | form) : redirect 1 Account * {accountId}/ GET() : xml | json | html PUT(xml | json | form) : xml | json | html DELETE() : redirect • Several APIs for on domain model
  21. 21. Lab : Specify your Pizza API PART 1 - API DESIGN (50’)
  22. 22. & Requirements gathering Requirements analysis
  23. 23. DESCRIBE PIZZA API PERSONAS Instructions • Contextual and specific to your API • Don’t denature a persona • Describe a total of 2 personas • Time limit: 10’
  24. 24. DESCRIBE PIZZA API USE CASES Instructions • Put your persona in context with use cases and derive features • Describe a total of 4 use cases (2 per persona) • Identify key features • Time limit: 10’
  25. 25. & Requirements analysis Solution design
  26. 26. DESCRIBE DOMAIN ENTITIES Advises • List 4 entities • Describe their properties • Including relationships • Time limit: 10’
  27. 27. IDENTIFY YOUR APIS Advises • Driven by personas and features • Describe 2 endpoints (1 for each API) • Several APIs should share the same domain model • Time limit: 5’
  28. 28. DESCRIBE API RESOURCES Advises • Driven by use cases • Derived from Domain Entities • Single and collection resources • Time limit: 15’
  29. 29. Solution design Next steps are about API deployment • Implement the Domain Entities – As a persistent store • Implement the Resource Model – As a Web API connected to the Domain Entities Design implementation • Choose between DIY and PaaS approaches
  30. 30. TIME FOR A BREAK ! (10’)
  31. 31. Info : APISpark as an IDE and runtime PART 2 - API DEPLOYMENT (5’)
  32. 32. WEB API PROJECT TYPICAL LIFE CYCLE 1) Do It Yourself (DIY) long, risky, expensive but highly flexible Create Host Manage Use 2) Platform as a Service (PaaS) integrated, fast, cost effective Promote
  33. 33. APISPARK PLATFORM CURRENTLY IN RESTRICTED PUBLIC BETA Send us your feed-back and help us making it the best PaaS for Web APIs !
  34. 34. COMPOSING APISPARK CELLS Java iOS HTTP JS HTTP Custom API Entity Store File Store
  35. 35. STRUCTURE OF WEB APIS HTTP HTTPS API Contract Web API template Complete web API Implementation Runtime
  36. 36. Lab : Deploy your Pizza API PART 2 - API DEPLOYMENT (35’)
  37. 37. SOCIAL LOGIN
  38. 38. YOUR DASHBOARD
  39. 39. ENTITY STORE CREATION
  40. 40. ENTITY PROPERTIES
  41. 41. WEB API CREATION
  42. 42. API GENERATION FROM ENTITY STORE
  43. 43. API DEPLOYMENT
  44. 44. CLIENT SDK GENERATION
  45. 45. Next steps are about closing the API loop Design implementation • Verify that the API works as expected – Manual tests – Automated tests • Functional tests • Performance tests (availability, latency, throughput, etc.) Implementation testing • Even more important in case of composite APIs
  46. 46. API TESTING WITH HTTP CLIENT
  47. 47. BUILT-IN ANALYTICS
  48. 48. CONCLUSION  Designing a web API requires thinking – The UX of developers using your API matters – Use a minimal but effective process  You can save a lot of time at deployment – Consider PaaS solutions versus DIY approaches – Easier and cheaper to get started and maintain – Think about multiple APIs and versions in 2 years
  49. 49. KEEP IN TOUCH! http://apispark.com http://blog.restlet.com Twitter: @apispark jlouvel@restlet.com Restlet undersigned this GigaOM research report, written by Kin Lane
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×