the api facade pattern: common patterns - episode 2
TRANSCRIPT
API Façade: Common Patterns
Episode 2Webinar ShortsMarch 2012 Series
Brian Mulloy@landlessness
Apigee@apigee
groups.google.com/group/api-craft
youtube.com/apigee
IRC Channel#api-crafton freenode
New!
Episode 1The API Facade: OverviewTuesday, March 6th
Episode 2The API Facade: Common PatternsTuesday, March 13th
Episode 3The API Facade: TechnologyTuesday, March 20th
Episode 4The API Facade: PeopleTuesday, March 27th
Webinar Shorts - March 2012 New!
Episode 2 Topics
• Recap: API façade• Errors• Stubs• URLs• Versioning• Data formats• Internal & external systems
Recap: API Façade
Big System
DBContent
Management SOAP JDBC RSS
API Facade
AppApp
Developer
RSSObjects
XML
App
1. Build up from systems of record
1.
Big System
DBContent
Management SOAP JDBC RSS
Tables
XML
RSS
XMLXML
Tables
XML
RSS
XML
One Big Problem
1. Design the Ideal API2. Implement Design with Stubs as Façade3. Mediate between Façade and SystemsApp
Developer
Mediate
API Facade
1.
2.
3.
Big System
DBContent
Management SOAP JDBC RSS
Ideal Design
Three Small Problems
Common patterns
Errors
When I say errors, you say test-driven development.
API Facade
Errors
Request Response
nothing to see here
200 201 304 400 401 403 404 500
{“developerMessage”:“Verbose, plain language description of the problem for the app developer with hints about how to fix it.”,“userMessage”:“Pass this message on to the app user, if needed.”,"errorCode":12345, ”status":401,“moreInfo”:“http://dev.teachdogrest.com/errors/12345”}
API Facade
Errors
Request Response
nothing to see here
GET /products?raise=500
(don’t support raise in production)
API Facade
Errors
Request Response
Big System
449 Retry With
404 Not Found
Stubs
API Facade
Stubs
Request Response
nothing to see here
{"products”: [ {"product":{"id":"1234”,"name":"Widget”, "color":"white"}},{"product":{"id":"1235”, "name":"Gadget”, "color":"brown"}} ]}
API Facade
Stubs
Request Response
nothing to see here
GET /products?mock=true
(don’t support mock in production)
URLs
URLs
/v2/accounts
AppDeveloper
URLs
Big System
/services/data/v20.0/sobjects/Account
API Facade
URLs
Request Response
Big System
/services/data/v20.0/sobjects/Account
/v2/accounts
API Facade
Support Limited Clients
Request Response
Big System
DELETE /services/data/v20.0/sobjects/Account/123
GET /v2/accounts/123?method=delete
Versioning
Versioning
/v3/accounts
Fast AppDeveloper
Slow AppDeveloper
/v2/accounts
API Facade
Versioning
Request
GET /v2/accounts GET /v3/accounts
Big OldSystem
New UntriedSystem
GET old.internal.com/accounts GET new.internal.com/accounts
Data Formats
Data Formats
JSON
HTML5 AppDeveloper
Java AppDeveloper
SOAP
SOAP
API Facade
Request Response
/services/data/v20.0/sobjects/Account
POST /v2/accounts.xml
SOAP
Data FormatsSOAP
SOAP
API Facade
Request Response
/services/data/v20.0/sobjects/Account
GET /v2/accounts.json
SOAP
Data FormatsJSON
Internal & external systems
DBContent
Management SOAP JDBC
API Facade
Internal
API Facade
External
SOAP RSSXML JSON
Q&A
Should the version number appear in the URL immediately after the domain name or is it better to have application name after domain name? Billing accounts /accounts/v2/create?
Q&A
With all the shunting you suggest make for a terrible complex layer?
Q&A
What would you recommend for a URL pattern for a sandbox instance?
Q&A
How can a GET request be transformed to a SOAP POST, specifically when the SOAP POST request size is huge?
Q&A
What about version in the request header instead of putting it in the URL, what would the drawback be of using it in the request header?
Q&A
Should every response follow a standard format that contains errors, if any, along with response body or should the response body change based on success or failure of the operation?
Q&A
What is the functional difference between the raise and the mock parameters again?
Q&A
For the API I am hosting façade pattern makes sense, but for the external systems where I am consuming APIs, factory seems more appropriate. What’s your take?
Q&A
What are your thoughts on REST sitemaps, worth it?
Q&A
Get flash accounts should return all accounts right? Wouldn’t want to prevent this, what would a URL request look like? If you’re reflecting a response from the database where the state=Washington, how would that work?
Q&A
THANK YOUSubscribe to API webinars at:
youtube.com/apigee
THANK YOUIRC#api-crafton freenode
THANK YOUQuestions and ideas to:
groups.google.com/group/api-craft
