architect's guide to building an api program

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