The API Facade Pattern: Common Patterns - Episode 2

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

THANK YOUContact me at:

@[email protected]