shared i/o state in api architecture
TRANSCRIPT
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