architect's guide to building an api program
DESCRIPTION
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.TRANSCRIPT
![Page 1: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/1.jpg)
Building an API ProgramAn architect’s survival guide
By Chris Latimer
![Page 2: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/2.jpg)
Why do we need APIs?
![Page 3: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/3.jpg)
More Devices / Platforms
![Page 4: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/4.jpg)
Agile Development
![Page 5: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/5.jpg)
Innovation
![Page 6: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/6.jpg)
Generate Income
![Page 7: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/7.jpg)
Drive Adoption
![Page 8: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/8.jpg)
How should we build an API program?
![Page 9: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/9.jpg)
Common Approach #1: Accidentally
![Page 10: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/10.jpg)
Web App
Browser ClientA project comes along
![Page 11: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/11.jpg)
Web App
Browser Client
An API is created
API
![Page 12: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/12.jpg)
Then more projects come along…
…and more APIs are created.
![Page 13: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/13.jpg)
The APIs are inconsistent
![Page 14: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/14.jpg)
Problems like caching and security are solved multiple times in multiple ways
![Page 15: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/15.jpg)
A major effort is considered to correct the course
![Page 16: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/16.jpg)
This approach usually doesn’t
end very well
![Page 17: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/17.jpg)
Common Approach #2: APIs as SOA++
![Page 18: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/18.jpg)
All APIs are designed and built in a top down fashion
![Page 19: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/19.jpg)
All APIs are heavily governed and treated as a critical business asset
Heavy weight governance is applied to all APIs
![Page 20: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/20.jpg)
Where this works
![Page 21: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/21.jpg)
APIs that are foundational to the organization’s strategy
![Page 22: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/22.jpg)
Example: Single source of truth for customer data
LOB CRM System
Billing System
Contract System
LOB CRM System
Customer API
![Page 23: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/23.jpg)
Where this approach gets stuck
![Page 24: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/24.jpg)
API program and projects move at different speeds and in different
directions.
![Page 25: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/25.jpg)
Approach #3: Value Driven APIs
![Page 26: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/26.jpg)
Focus on delivering value to your end users through apps.
![Page 27: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/27.jpg)
Build APIs that are easy for apps to consume.
What makes an API easy to consume?
![Page 28: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/28.jpg)
Is it using JSON payloads
instead of XML?
![Page 29: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/29.jpg)
Using this Template
Is it strict adherence to REST principles?
![Page 30: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/30.jpg)
API Fielding Score
![Page 31: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/31.jpg)
Using this Template
![Page 32: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/32.jpg)
Using this Template
Predictable and Consistent
![Page 33: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/33.jpg)
"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:
![Page 34: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/34.jpg)
<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" />
![Page 35: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/35.jpg)
Stable Versions
/v1/endpoint !
/v2/endpoint
Accept-‐Version: 1.0 !
Accept-‐Version: 1.1
URI Based Accept Header
Accept: application/vnd.your.api.v2+json !
Accept: application/vnd.your.api.v2.1+json
Content Type
![Page 36: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/36.jpg)
Predictable Response Codes
400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found
2xx Successful 4xx Client Error
500 Server Error 502 Bad Gateway 503 Unavailable
5xx Server Error
200 Success 201 Created !
![Page 37: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/37.jpg)
Using this Template
Intuitive Structure
![Page 38: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/38.jpg)
Using this Template
URI Description
/group/{id} A Facebook group
/group/{id}/feed This group’s feed
/group/{id}/files Files uploaded to this group
/group/{id}/events This group’s events
Intuitive URI Structure
![Page 39: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/39.jpg)
Using this Template
Intuitive Navigation
"total": 659212, "page": 2, "per_page": 10, "paging": { "next": "/channels?page=3", "previous": "/channels?page=1", "first": "/channels?page=1", "last": "/channels?page=65922" }
Pagination
![Page 40: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/40.jpg)
Using this Template
Intuitive Navigation
{ “uri": "/categories/experimental", "name": "Experimental", "subcategories": [ { "uri": “/categories/experimental/animation", "name": "Animation", "link": “https://vimeo.com/categories/…” }… ] }
Related Resources
![Page 41: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/41.jpg)
Flexible Responses
![Page 42: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/42.jpg)
Partial Responses
/feeds/api/users/default/uploads
Get Full Response
/feeds/api/users/default/uploads? \ fields=entry(title,gd:comments,yt:statistics)
Get Partial Response
![Page 43: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/43.jpg)
Result Filtering
/feeds/api/videos?q=surfing&max-‐results=10
Get List of Videos
/feeds/api/videos?q=surfing&max-‐results=10 &fields=entry[yt:statistics/@viewCount > 1000000]
Get Videos with 1,000,000+ Views
![Page 44: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/44.jpg)
Customized Responses
ItemId=B00008OE6I
ItemLookup - Default
ItemId=B00008OE6I &ResponseGroup=Reviews
ItemLookup - Default With Reviews
ItemId=B00008OE6I &ResponseGroup=Large,Reviews,Offers
ItemLookup - Large With Reviews and Offers
![Page 45: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/45.jpg)
Using this Template
Easy to Learn and Experiment With
![Page 46: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/46.jpg)
Using this Template
![Page 47: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/47.jpg)
Using this Template
![Page 48: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/48.jpg)
Create guidelines that make APIs and Apps easier to build
![Page 49: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/49.jpg)
Solve common problems such as caching,
security, analytics and access in a common framework / platform.
![Page 50: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/50.jpg)
All APIs are heavily governed and treated as a critical business asset
Don’t minimize governance. Minimize governance overhead.
![Page 51: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/51.jpg)
Pitfalls of this approach
Common API program pitfalls
![Page 52: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/52.jpg)
Demand for apps outpaces API development
![Page 53: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/53.jpg)
Expecting APIs to completely replace SOA
![Page 54: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/54.jpg)
SOA Problem - Orchestrate complex order placement process
Outsourced Supplier
Warehouse System
Accounting System
CRM System
Order Service
![Page 55: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/55.jpg)
API Problem - Make it easy to place an order from different apps
Order Service Order API
Browser Client
Partner Apps
![Page 56: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/56.jpg)
Not prioritizing critical traffic
![Page 57: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/57.jpg)
Not telling people where to find APIs or how to get access
![Page 58: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/58.jpg)
Not tracking API usage and consumers
![Page 59: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/59.jpg)
Focus on delivering value to your end users through apps.
![Page 60: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/60.jpg)
Build APIs that are easy for apps to consume.
![Page 61: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/61.jpg)
Pitfalls of this approach
Avoid common pitfalls
![Page 62: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/62.jpg)
And build a great API Program
![Page 63: Architect's Guide to Building an API Program](https://reader038.vdocuments.net/reader038/viewer/2022102816/55934a5e1a28ab10568b4730/html5/thumbnails/63.jpg)