SlideShare a Scribd company logo

The API Facade Pattern: Common Patterns - Episode 2

•Download as PPTX, PDF•
•
Apigee | Google Cloud
Apigee | Google Cloud

This document summarizes episode 2 of the API Facade webinar series, which discusses common patterns when implementing an API facade. The episode covers errors, stubs, URLs, versioning, data formats, and integrating internal and external systems. It also includes a question and answer section where attendees ask questions about these topics.

1 of 49
API Façade: Common Patterns Episode 2 Webinar Shorts March 2012 Series Brian Mulloy Apigee @landlessness @apigee
groups.google.com/group/api-craft
youtube.com/apigee
New! IRC Channel #api-craft on freenode
Webinar Shorts - March 2012 New! Episode 1 The API Facade: Overview Tuesday, March 6th Episode 2 The API Facade: Common Patterns Tuesday, March 13th Episode 3 The API Facade: Technology Tuesday, March 20th Episode 4 The API Facade: People Tuesday, March 27th
Episode 2 Topics • Recap: API façade • Errors • Stubs • URLs • Versioning • Data formats • Internal & external systems
Recap: API Façade
App App Developer API Facade Content Big DB Management JDBC RSS SOAP System
One Big Problem 1. Build up from systems of record App XML XML XML XML XML XML 1. Objects Tables RSS RSS Tables RSS Content Big DB Management JDBC RSS SOAP System
Three Small Problems 1. Design the Ideal API 2. Implement Design with Stubs as Façade App 3. Mediate between Façade and Systems Developer 1. Ideal Design 2. API Facade 3. Mediate Content Big DB Management JDBC RSS SOAP System
Common patterns
Errors
When I say errors, you say test-driven development.
Errors 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”} Request Response API Facade nothing to see here
Errors GET /products?raise=500 (don’t support raise in production) Request Response API Facade nothing to see here
Errors Request Response 404 Not Found API Facade 449 Retry With Big System
Stubs
Stubs {"products”: [ {"product":{"id":"1234”,"name":"Widget”, "color":"white"}} ,{"product":{"id":"1235”, "name":"Gadget”, "color":"brown" }} ] } Request Response API Facade nothing to see here
Stubs GET /products?mock=true (don’t support mock in production) Request Response API Facade nothing to see here
URLs
URLs App Developer /v2/accounts
URLs /services/data/v20.0/sobjects/Account Big System
URLs /v2/accounts Request Response API Facade /services/data/v20.0/sobjects/Account Big System
Support Limited Clients GET /v2/accounts/123?method=delete Request Response API Facade DELETE /services/data/v20.0/sobjects/Account/123 Big System
Versioning
Versioning Fast App Slow App Developer Developer /v3/accounts /v2/accounts
Versioning GET /v2/accounts GET /v3/accounts Request API Facade GET old.internal.com/accounts GET new.internal.com/accounts Big Old New Untried System System
Data Formats
Data Formats HTML5 App Java App Developer Developer JSON SOAP
Data Formats POST /v2/accounts.xml SOAP Request Response API Facade /services/data/v20.0/sobjects/Account SOAP SOAP
Data Formats GET /v2/accounts.json JSON Request Response API Facade /services/data/v20.0/sobjects/Account SOAP SOAP
Internal & external systems
Internal API Facade Content DB Management SOAP JDBC
External API Facade SOAP XML JSON RSS
Q&A
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?
THANK YOU Subscribe to API webinars at: youtube.com/apigee
THANK YOU IRC #api-craft on freenode
THANK YOU Questions and ideas to: groups.google.com/group/api-craft
THANK YOU Contact me at: @landlessness brian@apigee.com

More Related Content

The API Facade Pattern: Common Patterns - Episode 2

  • 1. API Façade: Common Patterns Episode 2 Webinar Shorts March 2012 Series Brian Mulloy Apigee @landlessness @apigee
  • 4. New! IRC Channel #api-craft on freenode
  • 5. Webinar Shorts - March 2012 New! Episode 1 The API Facade: Overview Tuesday, March 6th Episode 2 The API Facade: Common Patterns Tuesday, March 13th Episode 3 The API Facade: Technology Tuesday, March 20th Episode 4 The API Facade: People Tuesday, March 27th
  • 6. Episode 2 Topics • Recap: API façade • Errors • Stubs • URLs • Versioning • Data formats • Internal & external systems
  • 8. App App Developer API Facade Content Big DB Management JDBC RSS SOAP System
  • 9. One Big Problem 1. Build up from systems of record App XML XML XML XML XML XML 1. Objects Tables RSS RSS Tables RSS Content Big DB Management JDBC RSS SOAP System
  • 10. Three Small Problems 1. Design the Ideal API 2. Implement Design with Stubs as Façade App 3. Mediate between Façade and Systems Developer 1. Ideal Design 2. API Facade 3. Mediate Content Big DB Management JDBC RSS SOAP System
  • 13. When I say errors, you say test-driven development.
  • 14. Errors 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”} Request Response API Facade nothing to see here
  • 15. Errors GET /products?raise=500 (don’t support raise in production) Request Response API Facade nothing to see here
  • 16. Errors Request Response 404 Not Found API Facade 449 Retry With Big System
  • 17. Stubs
  • 18. Stubs {"products”: [ {"product":{"id":"1234”,"name":"Widget”, "color":"white"}} ,{"product":{"id":"1235”, "name":"Gadget”, "color":"brown" }} ] } Request Response API Facade nothing to see here
  • 19. Stubs GET /products?mock=true (don’t support mock in production) Request Response API Facade nothing to see here
  • 20. URLs
  • 21. URLs App Developer /v2/accounts
  • 23. URLs /v2/accounts Request Response API Facade /services/data/v20.0/sobjects/Account Big System
  • 24. Support Limited Clients GET /v2/accounts/123?method=delete Request Response API Facade DELETE /services/data/v20.0/sobjects/Account/123 Big System
  • 26. Versioning Fast App Slow App Developer Developer /v3/accounts /v2/accounts
  • 27. Versioning GET /v2/accounts GET /v3/accounts Request API Facade GET old.internal.com/accounts GET new.internal.com/accounts Big Old New Untried System System
  • 29. Data Formats HTML5 App Java App Developer Developer JSON SOAP
  • 30. Data Formats POST /v2/accounts.xml SOAP Request Response API Facade /services/data/v20.0/sobjects/Account SOAP SOAP
  • 31. Data Formats GET /v2/accounts.json JSON Request Response API Facade /services/data/v20.0/sobjects/Account SOAP SOAP
  • 33. Internal API Facade Content DB Management SOAP JDBC
  • 34. External API Facade SOAP XML JSON RSS
  • 35. Q&A
  • 36. 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?
  • 37. Q&A With all the shunting you suggest make for a terrible complex layer?
  • 38. Q&A What would you recommend for a URL pattern for a sandbox instance?
  • 39. Q&A How can a GET request be transformed to a SOAP POST, specifically when the SOAP POST request size is huge?
  • 40. 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?
  • 41. 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?
  • 42. Q&A What is the functional difference between the raise and the mock parameters again?
  • 43. 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?
  • 44. Q&A What are your thoughts on REST sitemaps, worth it?
  • 45. 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?
  • 46. THANK YOU Subscribe to API webinars at: youtube.com/apigee
  • 48. THANK YOU Questions and ideas to: groups.google.com/group/api-craft
  • 49. THANK YOU Contact me at: @landlessness brian@apigee.com

Editor's Notes

  1. Creative Commons Attribution-Share Alike 3.0 United States License