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. API Façade: Common Patterns
Episode 2
Webinar Shorts
March 2012 Series
Brian Mulloy Apigee
@landlessness @apigee

2. groups.google.com/group/api-craft

3. youtube.com/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

7. Recap: API Façade

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

11. Common patterns

12. Errors

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

22. URLs
/services/data/v20.0/sobjects/Account
Big System

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

25. Versioning

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

28. Data Formats

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

32. Internal & external systems

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

47. THANK YOU
IRC
#api-craft
on freenode

48. THANK YOU
Questions and ideas to:
groups.google.com/group/api-craft

49. THANK YOU
Contact me at:
@landlessness
brian@apigee.com