API Façade: Common PatternsEpisode 2Webinar ShortsMarch 2012 SeriesBrian Mulloy                   Apigee@landlessness     ...
groups.google.com/group/api-craft
youtube.com/apigee
New!       IRC Channel         #api-craft        on freenode
Webinar Shorts - March 2012       New!Episode 1The API Facade: OverviewTuesday, March 6thEpisode 2The API Facade: Common P...
Episode 2 Topics•   Recap: API façade•   Errors•   Stubs•   URLs•   Versioning•   Data formats•   Internal & external syst...
Recap: API Façade
App                     App                                  Developer                           API Facade               ...
One Big Problem                                   1. Build up from systems of record               App                    ...
Three Small Problems                        1. Design the Ideal API                        2. Implement Design with Stubs ...
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 descriptionof the problem ...
Errors          GET /products?raise=500            (don’t support raise in production)Request                             ...
ErrorsRequest                            Response                        404 Not Found           API Facade               ...
Stubs
Stubs{"products”:  [{"product":{"id":"1234”,"name":"Widget”, "color":"white"}},{"product":{"id":"1235”, "name":"Gadget”, "...
Stubs          GET /products?mock=true            (don’t support mock in production)Request                               ...
URLs
URLs    App  Developer/v2/accounts
URLs/services/data/v20.0/sobjects/Account             Big System
URLs       /v2/accounts          Request                       Response                          API Facade/services/data/...
Support Limited ClientsGET /v2/accounts/123?method=delete           Request                         Response              ...
Versioning
Versioning  Fast App      Slow App  Developer     Developer/v3/accounts   /v2/accounts
Versioning               GET /v2/accounts          GET /v3/accounts                             Request                   ...
Data Formats
Data FormatsHTML5 App   Java AppDeveloper   Developer  JSON       SOAP
Data Formats   POST /v2/accounts.xml                 SOAP          Request                       Response                 ...
Data Formats   GET /v2/accounts.json                 JSON          Request                       Response                 ...
Internal & external systems
Internal              API Facade       ContentDB   Management            SOAP   JDBC
External             API FacadeSOAP   XML                JSON   RSS
Q&A
Q&AShould the version number appear in the URL immediatelyafter the domain name or is it better to have application nameaf...
Q&AWith all the shunting you suggest make for a terrible complexlayer?
Q&AWhat would you recommend for a URL pattern for a sandboxinstance?
Q&AHow can a GET request be transformed to a SOAP POST,specifically when the SOAP POST request size is huge?
Q&AWhat about version in the request header instead of putting itin the URL, what would the drawback be of using it in the...
Q&AShould every response follow a standard format that containserrors, if any, along with response body or should the resp...
Q&AWhat is the functional difference between the raise and themock parameters again?
Q&AFor the API I am hosting façade pattern makes sense, but forthe external systems where I am consuming APIs, factory see...
Q&AWhat are your thoughts on REST sitemaps, worth it?
Q&AGet flash accounts should return all accounts right? Wouldn’twant to prevent this, what would a URL request look like? ...
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
THANK YOUContact me at:@landlessnessbrian@apigee.com
Upcoming SlideShare
Loading in...5
×

The API Facade Pattern: Common Patterns - Episode 2

9,353

Published on

Whether you are starting from a green field or brown, in this webinar we'll share common patterns of facades that will help you get your API initiative off the ground.
- Data format mediation
- URL design
- Authorization and versioning

Published in: Technology, Business
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
9,353
On Slideshare
0
From Embeds
0
Number of Embeds
7
Actions
Shares
0
Downloads
144
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide
  • Creative Commons Attribution-Share Alike 3.0 United States License
  • The API Facade Pattern: Common Patterns - Episode 2

    1. 1. API Façade: Common PatternsEpisode 2Webinar ShortsMarch 2012 SeriesBrian Mulloy Apigee@landlessness @apigee
    2. 2. groups.google.com/group/api-craft
    3. 3. youtube.com/apigee
    4. 4. New! IRC Channel #api-craft on freenode
    5. 5. Webinar Shorts - March 2012 New!Episode 1The API Facade: OverviewTuesday, March 6thEpisode 2The API Facade: Common PatternsTuesday, March 13thEpisode 3The API Facade: TechnologyTuesday, March 20thEpisode 4The API Facade: PeopleTuesday, March 27th
    6. 6. Episode 2 Topics• Recap: API façade• Errors• Stubs• URLs• Versioning• Data formats• Internal & external systems
    7. 7. Recap: API Façade
    8. 8. App App Developer API Facade Content Big DB Management JDBC RSS SOAPSystem
    9. 9. One Big Problem 1. Build up from systems of record App XML XML XML XML XML XML1. Objects Tables RSS RSS Tables RSS Content Big DB Management JDBC RSS SOAP System
    10. 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 Developer1. Ideal Design2. API Facade3. Mediate Content Big DB Management JDBC RSS SOAP System
    11. 11. Common patterns
    12. 12. Errors
    13. 13. When I say errors, you say test-driven development.
    14. 14. Errors 200 201 304 400 401 403 404 500{“developerMessage”:“Verbose, plain language descriptionof the problem for the app developer with hints about howto fix it.”,“userMessage”:“Pass this message on to the appuser, if needed.”,"errorCode":12345, ”status":401,“moreInfo”:“http://dev.teachdogrest.com/errors/12345”} Request Response API Facade nothing to see here
    15. 15. Errors GET /products?raise=500 (don’t support raise in production)Request Response API Facade nothing to see here
    16. 16. ErrorsRequest Response 404 Not Found API Facade 449 Retry With Big System
    17. 17. Stubs
    18. 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. 19. Stubs GET /products?mock=true (don’t support mock in production)Request Response API Facade nothing to see here
    20. 20. URLs
    21. 21. URLs App Developer/v2/accounts
    22. 22. URLs/services/data/v20.0/sobjects/Account Big System
    23. 23. URLs /v2/accounts Request Response API Facade/services/data/v20.0/sobjects/Account Big System
    24. 24. Support Limited ClientsGET /v2/accounts/123?method=delete Request Response API FacadeDELETE /services/data/v20.0/sobjects/Account/123 Big System
    25. 25. Versioning
    26. 26. Versioning Fast App Slow App Developer Developer/v3/accounts /v2/accounts
    27. 27. Versioning GET /v2/accounts GET /v3/accounts Request API FacadeGET old.internal.com/accounts GET new.internal.com/accounts Big Old New Untried System System
    28. 28. Data Formats
    29. 29. Data FormatsHTML5 App Java AppDeveloper Developer JSON SOAP
    30. 30. Data Formats POST /v2/accounts.xml SOAP Request Response API Facade/services/data/v20.0/sobjects/Account SOAP SOAP
    31. 31. Data Formats GET /v2/accounts.json JSON Request Response API Facade/services/data/v20.0/sobjects/Account SOAP SOAP
    32. 32. Internal & external systems
    33. 33. Internal API Facade ContentDB Management SOAP JDBC
    34. 34. External API FacadeSOAP XML JSON RSS
    35. 35. Q&A
    36. 36. Q&AShould the version number appear in the URL immediatelyafter the domain name or is it better to have application nameafter domain name? Billing accounts /accounts/v2/create?
    37. 37. Q&AWith all the shunting you suggest make for a terrible complexlayer?
    38. 38. Q&AWhat would you recommend for a URL pattern for a sandboxinstance?
    39. 39. Q&AHow can a GET request be transformed to a SOAP POST,specifically when the SOAP POST request size is huge?
    40. 40. Q&AWhat about version in the request header instead of putting itin the URL, what would the drawback be of using it in therequest header?
    41. 41. Q&AShould every response follow a standard format that containserrors, if any, along with response body or should the responsebody change based on success or failure of the operation?
    42. 42. Q&AWhat is the functional difference between the raise and themock parameters again?
    43. 43. Q&AFor the API I am hosting façade pattern makes sense, but forthe external systems where I am consuming APIs, factory seemsmore appropriate. What’s your take?
    44. 44. Q&AWhat are your thoughts on REST sitemaps, worth it?
    45. 45. Q&AGet flash accounts should return all accounts right? Wouldn’twant to prevent this, what would a URL request look like? Ifyou’re reflecting a response from the database where thestate=Washington, how would that work?
    46. 46. THANK YOUSubscribe to API webinars at:youtube.com/apigee
    47. 47. THANK YOUIRC#api-crafton freenode
    48. 48. THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
    49. 49. THANK YOUContact me at:@landlessnessbrian@apigee.com
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×