shared i/o state in api architecture

SPRINGONE2GXWASHINGTON, DC

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: ht tp: / /creat ivecommons.org/ l icenses/by-nc/3.0/

Shared I/O State in API ArchitectureBy Owen Rubel

@OwenRubel

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Owen Rubel• Original team member of Amazon 95-98

• Creator of API Chaining, API Abstraction and IO State

• Grails API Toolkit

• twitter: @owenrubel

• linkedin: https://www.linkedin.com/in/orubel

2

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

First a Warning…

3

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Centralized vs Distributed Architecture

• How many developers still use a centralized architecture vs a distributed architecture in their development?

4

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Centralized vs Distributed Architecture

• How many developers still use a centralized architecture vs a distributed architecture in their development?

• How many developers used a centralized architecture for their development 5 years ago? 10 years ago?

5

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Centralized vs Distributed Architecture

• How many developers still use a centralized architecture vs a distributed architecture in their development?

• How many developers used a centralized architecture for their development 5 years ago? 10 years ago?

• Pattern existed since the 80’s(???)

• Over the last 20 years, there has been a trend toward distributed architectures due to separation of services/concerns, micro services, and Aspect Oriented Programming

6

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

But What is The API Pattern?

7

“…specifies a software component in terms of its operations, their

inputs and outputs and underlying types. Its main purpose is to define

a set of functionalities that are independent of their respective

implementation…”

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Thus an API is:

• Separation of concern with a bound secondary concern

• communication logic bound to business logic

8

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

And There Are Two Ways To Implement:

• API As Software Pattern (Centralized Architecture)

• API As Architectural Pattern (Distributed Architecture)

9

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

API as a Software Pattern (Centralized Architecture)

10

I/O

RESOURCE MGMT

INPUT OUTPUTCOMMUNICATION

LOGICSERVICE w/ REQUEST

SERVICE w/ RESPONSE

SERVICES

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

API as an Architectural Pattern (Distributed Architecture)

11

I/O

RESOURCE MGMT

REQUEST RESPONSEHANDLER

INTERCEPTORCLIENT CLIENT

CONTROLLER

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

API as an Architectural Pattern (Distributed Architecture)

12

I/O

RESOURCE MGMT

REQUEST RESPONSEHANDLER

INTERCEPTORPROXY MQ

CONTROLLER

RE

QU

ES

TR

ES

PO

NS

E

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Sharing I/O Flow but NOT Sharing I/O Data

13

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

HANDLER INTERCEPTOR

Mixed Implementation : Software Pattern in an Architectural Pattern (Part 1)

14

REQUEST

COMMUNICATION LOGIC

PROXY MQ

CONTROLLER

RESPONSE

RestfulController,@RequestMapping,@RequestParam,@ResponseBody,@PathVariable

I/O

RESOURCE MGMT

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Mixed Patterns: Issues?

• Duplicate Code

• Duplicate Handling of Flow

• Software Confusion

• Architectural Confusion

• Cross Cutting Concerns

• Inability to share I/O state with services that share I/O flow

15

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Mixed Implementation: Duplicitous Code (Part 2)

16

@Secured(['ROLE_ADMIN', ‘ROLE_USER'])@RequestMapping(value="/create", method=RequestMethod.POST)@ResponseBodypublic ModelAndView createAddress(){ List authorities = springSecurityService.getPrincipal().getAuthorities() User user if(authorities.contains(‘ROLE_ADMIN’)){

if(params.id){ user = User.get(params.id.toLong())

}else{ render(status:HttpServletResponse.SC_BAD_REQUEST)

} }else if(authorities.contains(‘ROLE_USER’)){

user = User.get(principal.id) } Address address = new Address(params) address.user = user … }

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Mixed Implementation :Manually Coding of Flow (Part 3)

17

REQUEST

COMMUNICATION LOGIC

PROXY MQ

CONTROLLER

RESPONSE

Automatedflow

PRE POST

Manually Encodedflow per method

HANDLER INTERCEPTOR

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Mixed Implementation :Dropped Threads (Part 3)

18

REQUEST

COMMUNICATION LOGIC

PROXY w/ Security

MQ

CONTROLLER

RESPONSEPRE POST

HANDLER

Dropped Thread and IO boundREDIRECT

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

“This Fixes Everything That We Are Currently Having Issues With!”

19

- API Manager, Netflix

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Mixed Architecture: Inability to Share Data w/ Architecture (Part 4)

20

HANDLER INTERCEPTOR

REQUEST

COMMUNICATION

PROXY MQ

CONTROLLER

RESPONSEpost/show/1

{GET,JSON, ROLE_ADMIN}

{…}

RestfulController,@RequestMapping,@RequestParam,@ResponseBody,@PathVariable

???

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

The API Pattern is Either Application OR Architecture… But Not Both!

21

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Benefits of an API as Architecture?

• Easier to abstract components

• Once components abstracted, easier to share with services using IO flow

• Can separate data from functionality

• Check security early and late in proxy and MQ; can also check security in

handlerInterceptor on redirect/forward.

• More Scalable… both Vertically and Horizontally due to better separation.

• Made for Automation (Batching, api chaining, api doc generation based on roles, etc)

• Api Multi-tenancy (functionality can be split, combined, joined without application rewrite)

• Vast reduction in code required; no duplication in controllers.

• Shared IO State for sharing with IO flow

22

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

So How Do We Solve?

23

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Web API (as the Application) : Shared Architecture

24

REQUEST RESPONSEHANDLER

INTERCEPTORPROXY MQ

CONTROLLERI/O

RESOURCE MGMT

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

So How Do We Share the Data Across the Architecture?

25

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Cached I/O State in Architecture

26

REQUEST

HANDLER INTERCEPTOR

PROXY MQ

CONTROLLER

CACHE (I/O STATE)

SUB/PUB

RESPONSE

SUB/PUB

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

So What is I/O State?

27

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

I/O State : Communications Rules

28

I/O State is data directly related to a request/response, normally separated from functionality. Handles all data associated with communication and communication access

• Caches Communications Data • Synchronizes Architectural Properties • Handles API Authorizations • Api Docs Definitions

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

I/O State

29

• all the data contained in annotations act as rules associated with the uri endpoint

• by containing all those rules in one file and caching that data, we can share it with

the other architectural components

• this enables us to change it on the fly and reload without having to restart any

services and subscribed services will have changes published to them through

web hooks

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

I/O State : A Cached Communications Property File

30

Shared I/O State is ‘IO State’ data unbound from functionality so that it can be shared across architectural components. This is the approach used by distributed architectures.

Bound I/O State is ‘I/O State’ data bound to functionality which cannot be shared or synchronized with additional architectural components creating an ‘architectural cross cutting concern’. This is commonly found in centralized architectures.

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Shared I/O State

• DOESN’T bind to the application • DOESN’T bind to functionality • DOESN’T bind to a resource

31

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

What Does It Look Like?

32

https://gist.github.com/orubel/7c4d0290c7b8896667a3

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

What Shared I/O State Maintains…

33

• Values provided for Input/Output • All Endpoints • Endpoint Authorization (ie Roles) • Endpoint Request Method (GET, PUT, POST, DELETE) • Expected Input per Endpoint • Expected Output per Endpoint • Version for document • Deprecation Date for document • Batching Authorization (and toggle) • and more

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Similar technologies (and How They Compare)• Api Blueprint

• confuses I/O state with delivery content (which doesn’t need to be shared)

• duplicitous; lack of separation

• no roles

• Swagger

• not role based

• based on annotations and thus not sharable in distributed architecture

• only focused on API docs

• duplicitous; lack of separation

• RAML

• not role based

• limited to ‘traditional’ REST of 4 calls per class

• duplicitous; lack of separation

34

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Controller : Mixed Concerns (Duplication)

35

@Secured(['ROLE_ADMIN', ‘ROLE_USER'])@RequestMapping(value="/create", method=RequestMethod.POST)@ResponseBodypublic ModelAndView createAddress(){ List authorities = springSecurityService.getPrincipal().getAuthorities() User user if(authorities.contains(‘ROLE_ADMIN’)){

if(params.id){ user = User.get(params.id.toLong())

}else{ render(status:HttpServletResponse.SC_BAD_REQUEST)

} }else if(authorities.contains(‘ROLE_USER’)){

user = User.get(principal.id) } Address address = new Address(params) address.user = user … }

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Controller : Mixed Concerns (Duplication)

36

@RequestMapping(value="/create", method=RequestMethod.POST)@ResponseBodypublic ModelAndView createAddress(){ User user= (params.id)?User.get(params.id.toLong()): User.get(principal.id) Address address = new Address(params) address.user = user … }

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Controller : Single Concern

37

public ModelAndView createAddress(){ User user= (params.id)?User.get(params.id.toLong()): User.get(principal.id) Address address = new Address(params) address.user = user … }

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Ok But How Does it Work W/O Annotations?

38

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Bootstrap : Load Data into Cache

39

class ApiBootStrap {

def apiObjectService

def init = { servletContext ->apiObjectService.initialize()

}

def destroy = {}

}

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Url Mapping : Map Endpoints

40

static mappings = {

String apiVersion = getGrailsApplication().metadata['info.app.version'] String api = "v${apiVersion}"

// REGULAR API ENDPOINTS "/$api/$controller/$action?/$id?(.$format)?"{ parseRequest = true }

"/$api/$controller/$action/$id**" { parseRequest = true }

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

HandlerInterceptor: Run checks on Requests Against Cache

41

boolean before(){ LinkedHashMap cache = (params.controller)?apiCacheService.getApiCache(params.controller):[:] if(cache){ boolean result = apiRequestService.handleApiRequest(cache,request,params) return result} return false}

boolean after(){ Map newModel = (model)?apiResponseService.convertModel(model):model Map cache = (params.controller)?apiCacheService.getApiCache(params.controller):[:] Map content = apiResponseService.handleApiResponse(cache,request,response,newModel,params) if(content){ render(text:content.apiToolkitContent, contentType:"${content.apiToolkitType}", encoding:content.apiToolkitEncoding) return false}return false}

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Flow

42

PREHANDLER REQUESTSERVICE POSTHANDLER RESPONSESERVICECONTROLLER

request

response

after()

controller/action

handleApiRequest

handleApiResponse

model, headers, etc

true/falsefalsetrue

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

To Create Something Like This…

43

https://gist.github.com/orubel/d5b161332b5a788828eb

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Demo

44

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: http://creativecommons.org/licenses/by-nc/3.0/

Questions?

45

SPRINGONE2GXWASHINGTON, DC

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: ht tp: / /creat ivecommons.org/ l icenses/by-nc/3.0/

• API Chaining and API Abstraction (http://www.slideshare.net/bobdobbes/api-

abstraction-api-chaining)

• The API is Dead, Long Live The API (http://www.dev9.com/article/2015/9/api-is-

dead)

• Why the API Pattern is Broken and How We Can Fix It (http://apievangelist.com/

2015/05/05/guest-post-why-the-api-pattern-is-broken-and-how-we-can-fix-it/)

Additional Links