The API pattern bind IO functionality to business functionality by binding IO state either through annotation (ie JAX) or by extending a RestfulController. As a result, the data associated IO State cannot be shared with the architectural instances because it is bound to the controller. This creates architectural cross cutting concerns not only with the functionality but also with the data. By abstracting the functionality, we can create a versioned data object for IO state that can be shared,cached,synced,reloaded on the fly for all architectural instances without having to restart any instance. This greatly improve automation, performance and flow of api applications and architecture.

1. SPRINGONE2GX
WASHINGTON, DC
Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a Creative Commons Attributio n-NonCommercial license: http://creativecommons.org/licenses/by -nc/3.0/
Shared I/O State in API
Architecture
By Owen Rubel
@OwenRubel

2. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

3. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
First a Warning…
3

4. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

5. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

6. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

7. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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…”

8. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

9. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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

10. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
API as a Software Pattern (Centralized Architecture)
10
I/O
RESOURCE MGMT
REQUEST RESPONSE
COMMUNICATION
LOGIC
CLIENT CLIENT
CONTROLLER

11. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
API as an Architectural Pattern (Distributed Architecture)
11
I/O
RESOURCE MGMT
REQUEST RESPONSE
HANDLER
INTERCEPTOR
PROXY MQ
CONTROLLER
REQUEST
RESPONSE

12. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Sharing I/O Flow but NOT Sharing I/O Data
12

13. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
HANDLER
INTERCEPTOR
Mixed Implementation : Software Pattern in an Architectural Pattern
(Part 1)
13
REQUEST
COMMUNICATION
LOGIC
PROXY MQ
CONTROLLER
RESPONSE
RestfulController,
@RequestMapping,
@RequestParam,
@ResponseBody,
@PathVariable
I/O
RESOURCE MGMT

14. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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
14

15. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Mixed Implementation: Duplicitous Code (Part 2)
15
@Secured(['ROLE_ADMIN', ‘ROLE_USER'])
@RequestMapping(value="/create", method=RequestMethod.POST)
@ResponseBody
public 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
…
}

16. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Mixed Implementation :Manually Coding of Flow (Part 3)
16
REQUEST
COMMUNICATION
LOGIC
PROXY MQ
CONTROLLER
RESPONSE
Automated
flow
PRE POST
Manually Encoded
flow per method
HANDLER INTERCEPTOR

17. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Mixed Implementation :Dropped Threads (Part 3)
17
REQUEST
COMMUNICATION
LOGIC
PROXY
w/ Security
MQ
CONTROLLER
RESPONSEPRE POST
HANDLER
INTERCEPTOR
Dropped Thread and IO bound
REDIRECT

18. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
“This Fixes Everything That We Are Currently
Having Issues With!”
18
- API Manager, Netflix

19. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Mixed Architecture: Inability to Share Data w/ Architecture (Part 4)
19
HANDLER
INTERCEPTO
R
REQUES
T
COMMUNICATION
LOGIC
PROX
Y
MQ
CONTROLLE
R
RESPONS
E
post/show/1
{GET,JSON,
ROLE_ADMIN
} {…}
RestfulController,
@RequestMapping,
@RequestParam,
@ResponseBody,
@PathVariable
???

20. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
The API Pattern is Either Application OR
Architecture…
But Not Both!
20

21. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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
21

22. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
So How Do We Solve?
22

23. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Web API (as the Application) : Shared Architecture
23
REQUEST RESPONSE
HANDLER
INTERCEPTOR
PROXY MQ
CONTROLLER
I/O
RESOURCE MGMT

24. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
So How Do We Share the Data Across the
Architecture?
24

25. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Cached I/O State in Architecture
25
REQUEST
HANDLER
INTERCEPTOR
PROXY MQ
CONTROLLER
CACHE (I/O STATE)
SUB/PUB
RESPONSE
SUB/PUB

26. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
So What is I/O State?
26

27. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
I/O State : Communications Rules
27
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

28. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
I/O State
28
• 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

29. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
I/O State : A Cached Communications Property File
29
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.

30. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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
30

31. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
What Does It Look Like?
31
https://gist.github.com/orubel/7c4d0290c7b8896667a3

32. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
What Shared I/O State Maintains…
32
• 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

33. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: 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
33

34. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Controller : Mixed Concerns (Duplication)
34
@Secured(['ROLE_ADMIN', ‘ROLE_USER'])
@RequestMapping(value="/create", method=RequestMethod.POST)
@ResponseBody
public 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
…
}

35. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Controller : Mixed Concerns (Duplication)
35
@RequestMapping(value="/create", method=RequestMethod.POST)
@ResponseBody
public ModelAndView createAddress(){
User user= (params.id)?User.get(params.id.toLong()): User.get(principal.id)
Address address = new Address(params)
address.user = user
…
}

36. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Controller : Single Concern
36
public ModelAndView createAddress(){
User user= (params.id)?User.get(params.id.toLong()): User.get(principal.id)
Address address = new Address(params)
address.user = user
…
}

37. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Ok But How Does it Work W/O Annotations?
37

38. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Bootstrap : Load Data into Cache
38
class ApiBootStrap {
def apiObjectService
def init = { servletContext ->
apiObjectService.initialize()
}
def destroy = {}
}

39. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Url Mapping : Map Endpoints
39
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
}

40. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
HandlerInterceptor: Run checks on Requests Against Cache
40
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
}

41. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Flow
41
PREHANDLER REQUESTSERVICE POSTHANDLER RESPONSESERVICECONTROLLER
request
response
after()
controller/action
handleApiRequest
handleApiResponse
model, headers, etc
true/falsefalse
true

42. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
To Create Something Like This…
42
https://gist.github.com/orubel/d5b161332b5a788828eb

43. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Demo
43

44. Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a
Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
Questions?
44

45. SPRINGONE2GX
WASHINGTON, DC
Unless otherwise indicated, these slides are © 2013 -2015 Pivotal Software, Inc. and licensed under a Creative Commons Attributio n-NonCommercial license: http://creativecommons.org/licenses/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