Embed Size (px)
DESCRIPTION
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.
Citation preview
DESIGN & DEPLOYA DATA-DRIVEN API IN 2 HOURS
All-in-one platform for Web APIshttp://apispark.com
October 23, 2013
Restlet undersigned this GigaOMresearch report, written by Kin Lane
PRESENTERENTREPRENEUR 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
Twitter : @jlouvel and Google+
Blog : blog.restlet.com
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
PART 1 - API DESIGN (15’)
Info : The ROA/D to API design
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…
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 !
ITERATION STEPS
Requirements gathering
Requirements analysis
Solutiondesign
Designimplementation
Implementationtesting
PROJECT PHASES
Inception Elaboration Construction Transition
Each phase contains– Several iterations
– More requirements & analysis in early phases
– More implementation & testing in later phases
&
UX Design for API Developers
• UX != UI UXD != API
• Similar process:– User research Persona Use case Feature(s)
• Enrich ROA/D during– Requirements
– Analysis
• Based on Nazmul and Izabel Idrisworkshop for Google I/O 13– http://bit.ly/uxcommunity
– Adapted to web APIs byAPISpark with help of SFEIR
Requirements gathering
Requirementsanalysis
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
• Contextual and specific to your API
• Don’t denature a persona
• Don’t support too many personas
• Think about gameconsoles, connectedTV / cars, glue scripts
Advises
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
• Identify use cases per persona
• Derive features from concrete use cases
• Be careful about feature creep!
Advises
BALANCE API FEATURESSIMPLICITY VS CAPABILITY
Complexity
Capability
Simplistic and
frustrating
Powerful but
unusable
Adding
features
Adding
features
Good UX
design
Bad UX
design
Your web APIsweet spot
Requirements analysis
Solutiondesign
&
Domain-Driven Design for API Developers
• When your domain isn’t trivial
• Key building blocks– Entity
– Service
– Repository
• Enrich ROA/D during– Analysis
– Design
• Based on Eric Evans book
IDENTIFY DOMAIN ENTITIES
• Defined by thread of continuity
• Has own identity
• Not defined by its properties (value objects)
AdvisesCustomer
Invoice
Order
?
DESCRIBE DOMAIN ENTITIES
• Describe properties
• Describe relationships
• Use class diagrams
Advises
id : String
name : String
created : Date
modified : Date
Customer
id : String
amount : Integer
iterms : List<InvoiceItem>
modified : Date
Invoice
id : String
amount : Integer
iterms : List<OrderItem>
modified : Date
Order
*
1
*
Requirements analysis
Solutiondesign
Next design steps are more API specific
• Define your logical architecture– Learn about Netflix API strategy
• Derive your domain entities into– API resources
– Domain objects
– Data tables
• Design your API resources– URI templates
– Representations structure
– Supported HTTP methods
UI
API resources
Domain objects
Data tables
_+
Reusable
LOGICAL ARCHITECTURE
DERIVING THE DOMAIN MODEL
Data
tables
ROA/D OOA/D IDEF1
ROM ORM
Domain
entities
Domain
objects
API
resources
IDENTIFY YOUR APIS
• Driven by personas
• Each persona might need a specific API
• All APIs should share the same domain model
Advises
DomainModel
Pages + API
Browser
Connected mobile devices
Smartenvironnement
Partner Internal IS
DESCRIBE API RESOURCES
• Driven by use cases
• Derived from Domain Entities
• Several APIs for on domain model
Advises
Account
{accountId}/
GET() : xml | json | html
PUT(xml | json | form) : xml | json | html
DELETE() : redirect
Accounts
accounts/
GET() : xml | json | html
POST(xml | json | form) : redirect
1
*
Root
http://localhost:8111/
GET() : xml | json | html
1
1
PART 1 - API DESIGN (50’)
Lab : Specify your Pizza API
&
Requirements gathering
Requirementsanalysis
DESCRIBE PIZZA API PERSONAS
• Contextual and specific to your API
• Don’t denature a persona
• Describe a total of 2 personas
• Time limit: 10’
Instructions
DESCRIBE PIZZA API USE CASES
• 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’
Instructions
Requirements analysis
Solutiondesign
&
DESCRIBE DOMAIN ENTITIES
• List 4 entities
• Describe their properties
• Including relationships
• Time limit: 10’
Advises
IDENTIFY YOUR APIS
• Driven by personas and features
• Describe 2 endpoints (1 for each API)
• Several APIs should share the same domain model
• Time limit: 5’
Advises
DESCRIBE API RESOURCES
• Driven by use cases
• Derived from Domain Entities
• Single and collection resources
• Time limit: 15’
Advises
Solutiondesign
Design
implementation
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
• Choose between DIY and PaaS approaches
TIME FOR A BREAK ! (10’)
PART 2 - API DEPLOYMENT (5’)
Info : APISpark as an IDE and runtime
WEB API PROJECTTYPICAL LIFE CYCLE
Create Host Manage Use Promote
1) Do It Yourself (DIY)
long, risky, expensive but highly flexible
2) Platform as a Service (PaaS)
integrated, fast, cost effective
APISPARK PLATFORMCURRENTLY IN RESTRICTED PUBLIC BETA
Send us your feed-back and help us making it the best PaaS for Web APIs !
COMPOSING APISPARK CELLS
Entity Store File Store
Custom API
Java iOS JS
HTTP HTTP
STRUCTURE OF WEB APIS
API Contract
Implementation
Runtime
Web API
template
Completeweb API
HTTP HTTPS
PART 2 - API DEPLOYMENT (35’)
Lab : Deploy your Pizza API
SOCIAL LOGIN
YOUR DASHBOARD
ENTITY STORE CREATION
ENTITY PROPERTIES
WEB API CREATION
API GENERATION FROM ENTITY STORE
API DEPLOYMENT
CLIENT SDK GENERATION
Designimplementation
Implementationtesting
Next steps are about closing the API loop
• Verify that the API works as expected– Manual tests
– Automated tests
• Functional tests
• Performance tests (availability, latency, throughput, etc.)
• Even more important in case of composite APIs
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 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
KEEP IN TOUCH!
http://apispark.com
http://blog.restlet.com
Twitter: @apispark
[email protected] Restlet undersigned this GigaOMresearch report, written by Kin Lane
