This talk explores the motivation for creating APIs, common approaches organizations take when building an API program, the types of standards that architects should strive to put in place, and common pitfalls that organizations encounter.

1. Building an API Program
An architect’s survival guide
By Chris Latimer

2. Why do we need
APIs?

3. More Devices / Platforms

4. Agile Development

5. Innovation

6. Generate Income

7. Drive Adoption

8. How should we build an API
program?

9. Common Approach #1: Accidentally

10. Browser Client
Web App
A project comes along

11. Browser Client
Web App
An API is created
API

12. Then more projects
come along…
…and more APIs are
created.

13. The APIs are inconsistent

14. Problems like caching and
security are solved
multiple times in
multiple ways

15. A major effort is considered to
correct the course

16. This approach
usually doesn’t
end very
well

17. Common Approach
#2: APIs as SOA++

18. All APIs are designed and
built in a top down fashion

19. Heavy weight governance is
applied to all APIs
All APIs are heavily
governed and treated as
a critical business asset

20. Where this works

21. APIs that are foundational to the
organization’s strategy

22. Example: Single source
of truth for customer data
LOB CRM System
LOB CRM System
Billing System
Contract System
Customer API

23. Where this approach gets stuck

24. API program and projects move at
different speeds and in different
directions.

25. Approach #3:
Value Driven APIs

26. Focus on delivering
value to your end users
through apps.

27. Build APIs that are easy for apps to
consume.
What makes an API easy to consume?

28. Is it using JSON
payloads
instead of XML?

29. Is it strict adherence to REST principles?
Using this Template

30. API Fielding Score

31. Using this Template

32. Using this Template
Predictable and Consistent

33. "uri":
"/categories/activism",
"name":
"Activism
&
Non
Profits",
"link":
“https://vimeo.com/…”,
…
"metadata":
{
"connections":
{…}
}
Category !
Response:
"uri":
"/channels/804185",
"name":
"School
Intercom",
"link":
“https://vimeo.com/…”,
…
"metadata":
{
"connections":
{…}
}
Channel !
Response:

34. <photo
id="2636"
owner="47058503995@N01"
secret="a123456"
server=“2"
title=“test_04”
ispublic=“1"
isfriend="0"
isfamily="0"
/>
<contact
nsid="12037949629@N01"
username="Eric"
iconserver="1"
realname="Eric
Costello"
friend="1"
family="0"
ignored="1"
/>

35. Stable Versions
URI Based Accept Header
/v1/endpoint
!
/v2/endpoint
Accept-­‐Version:
1.0
!
Accept-­‐Version:
1.1
Content Type
Accept:
application/vnd.your.api.v2+json
!
Accept:
application/vnd.your.api.v2.1+json

36. Predictable Response Codes
2xx Successful 4xx Client Error
400
Bad
Request
401
Unauthorized
403
Forbidden
404
Not
Found
5xx Server Error
500
Server
Error
502
Bad
Gateway
503
Unavailable
200
Success
201
Created
!

37. Using this Template
Intuitive Structure

38. Intuitive URI Structure
URI Description
/group/{id} A Facebook group
Using this Template
/group/{id}/feed This group’s feed
/group/{id}/files Files uploaded to this group
/group/{id}/events This group’s events

39. Intuitive Navigation
Pagination
"total":
659212,
"page":
2,
"per_page":
10,
"paging":
{
"next":
"/channels?page=3",
"previous":
"/channels?page=1",
"first":
"/channels?page=1",
"last":
"/channels?page=65922"
}
Using this Template

40. Intuitive Navigation
Related Resources
{
“uri":
"/categories/experimental",
"name":
"Experimental",
"subcategories":
[
Using this Template
{
"uri":
“/categories/experimental/animation",
"name":
"Animation",
"link":
“https://vimeo.com/categories/…”
}…
]
}

41. Flexible Responses

42. Partial Responses
Get Full Response
/feeds/api/users/default/uploads
Get Partial Response
/feeds/api/users/default/uploads?
fields=entry(title,gd:comments,yt:statistics)

43. Result Filtering
Get List of Videos
/feeds/api/videos?q=surfing&max-­‐results=10
Get Videos with 1,000,000+ Views
/feeds/api/videos?q=surfing&max-­‐results=10
&fields=entry[yt:statistics/@viewCount
>
1000000]

44. Customized Responses
ItemLookup - Default
ItemId=B00008OE6I
ItemLookup - Default With Reviews
ItemId=B00008OE6I
&ResponseGroup=Reviews
ItemLookup - Large With Reviews and Offers
ItemId=B00008OE6I
&ResponseGroup=Large,Reviews,Offers

45. Easy to Learn and
Experiment With
Using this Template

46. Using this Template

47. Using this Template

48. Create guidelines that make APIs and
Apps easier to build

49. Solve common problems
such as caching,
security, analytics and
access in a common
framework / platform.

50. Don’t minimize governance.
Minimize governance overhead.
All APIs are heavily
governed and treated as
a critical business asset

51. Common API program pitfalls
Pitfalls of this
approach

52. Demand for apps outpaces API
development

53. Expecting APIs to
completely replace SOA

54. SOA Problem - Orchestrate
complex order placement process
CRM System
Outsourced Supplier
Warehouse System
Accounting System
Order Service

55. API Problem - Make it easy to
place an order from different apps
Order Service Order API
Browser Client
Partner Apps

56. Not prioritizing critical traffic

57. Not telling people where to find
APIs or how to get access

58. Not tracking API
usage and consumers

59. Focus on delivering
value to your end users
through apps.

60. Build APIs that are easy for apps to
consume.

61. Avoid common pitfalls
Pitfalls of this
approach

62. And build a great
API Program