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

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

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

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

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

 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

Implementation
testing

Design
implementation

Requirements
analysis

Solution
design

PROJECT PHASES
 Each phase contains
– Several iterations
– More requirements & analysis in early phases
– More implementation & testing in later phases

Inception

Elaboration

Construction

Transition

&
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

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

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!

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

&
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

IDENTIFY DOMAIN ENTITIES
Advises
Customer

• Defined by thread
of continuity
Invoice
Order

• Has own identity

?

• Not defined by its
properties (
value objects)

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

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

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

• Each persona might
need a specific API

Domain
Model
Partner

Internal IS

• All APIs should
share the same
domain model

DESCRIBE API RESOURCES
Advises

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

• Driven by use
cases

1
Accounts
1

accounts/

• Derived from
Domain Entities

POST(xml | json | form) : redirect
1

Account

*

{accountId}/
PUT(xml | json | form) : xml | json | html
DELETE() : redirect

• Several APIs for
on domain model

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 total of 2
personas
• Time limit: 10’

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’

&

Requirements
analysis

Solution
design

DESCRIBE DOMAIN ENTITIES
Advises
• List 4 entities
• Describe their
properties
• Including
relationships

IDENTIFY YOUR APIS
Advises
• Driven by personas
and features

• Describe 2 endpoints
(1 for each API)
• Several APIs should
share the same
domain model

DESCRIBE API RESOURCES
Advises
• Driven by use cases

• Derived from
Domain Entities
• Single and
collection resources

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

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

Manage

Use

2) Platform as a Service (PaaS)
integrated, fast, cost effective

Promote

APISPARK PLATFORM
CURRENTLY IN RESTRICTED PUBLIC BETA

Send us your feed-back
and help us making it the
best PaaS for Web APIs !

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’)

API GENERATION FROM ENTITY STORE

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

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
jlouvel@restlet.com

Restlet undersigned this GigaOM
research report, written by Kin Lane

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

Recommended

More Related Content

What's hot (20)

Similar to Design & Deploy a data-driven Web API in 2 hours (20)

More from Restlet (20)

Recently uploaded (20)

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