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
Building an API ProgramAn architect’s survival guide
By Chris Latimer
Why do we need APIs?
More Devices / Platforms
Agile Development
Innovation
Generate Income
Drive Adoption
How should we build an API program?
Common Approach #1: Accidentally
Web App
Browser ClientA project comes along
Web App
Browser Client
An API is created
API
Then more projects come along…
…and more APIs are created.
The APIs are inconsistent
Problems like caching and security are solved multiple times in multiple ways
A major effort is considered to correct the course
This approach usually doesn’t
end very well
Common Approach #2: APIs as SOA++
All APIs are designed and built in a top down fashion
All APIs are heavily governed and treated as a critical business asset
Heavy weight governance is applied to all APIs
Where this works
APIs that are foundational to the organization’s strategy
Example: Single source of truth for customer data
LOB CRM System
Billing System
Contract System
LOB CRM System
Customer API
Where this approach gets stuck
API program and projects move at different speeds and in different
directions.
Approach #3: Value Driven APIs
Focus on delivering value to your end users through apps.
Build APIs that are easy for apps to consume.
What makes an API easy to consume?
Is it using JSON payloads
instead of XML?
Using this Template
Is it strict adherence to REST principles?
API Fielding Score
Using this Template
Using this Template
Predictable and Consistent
"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:
<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" />
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
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 !
Using this Template
Intuitive Structure
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
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
Using this Template
Intuitive Navigation
{ “uri": "/categories/experimental", "name": "Experimental", "subcategories": [ { "uri": “/categories/experimental/animation", "name": "Animation", "link": “https://vimeo.com/categories/…” }… ] }
Related Resources
Flexible Responses
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
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
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
Using this Template
Easy to Learn and Experiment With
Using this Template
Using this Template
Create guidelines that make APIs and Apps easier to build
Solve common problems such as caching,
security, analytics and access in a common framework / platform.
All APIs are heavily governed and treated as a critical business asset
Don’t minimize governance. Minimize governance overhead.
Pitfalls of this approach
Common API program pitfalls
Demand for apps outpaces API development
Expecting APIs to completely replace SOA
SOA Problem - Orchestrate complex order placement process
Outsourced Supplier
Warehouse System
Accounting System
CRM System
Order Service
API Problem - Make it easy to place an order from different apps
Order Service Order API
Browser Client
Partner Apps
Not prioritizing critical traffic
Not telling people where to find APIs or how to get access
Not tracking API usage and consumers
Focus on delivering value to your end users through apps.
Build APIs that are easy for apps to consume.
Pitfalls of this approach
Avoid common pitfalls
And build a great API Program