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

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

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

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

jlouvel@restlet.com Restlet undersigned this GigaOMresearch report, written by Kin Lane