API Design - 3rd Edition

API Design
3rd Edition

Brian Mulloy
@landlessness
Kevin Swiber Apigee
@kevinswiber @apigee

groups.google.com/group/api-craft

“ The real issue is about design: designing
things that have the power required for the
job while maintaining understandability, the
feeling of control, and the pleasure of
accomplishment.
-Donald Norman

http://www.flickr.com/photos/mattharvey1/5712604622/

Agenda
• Recap Previous Edition
• API Modeling
• Security
• Message Design
• Hypermedia
• Transactions

http://offers.apigee.com/web-api-design-ebook/

URL Design Versioning
Plural nouns for /dogs Include version in /v1/dogs
collections URL
ID for entity /dogs/1234 Keep one previous /v1/dogs
version long /v2/dogs
Associations /owners/5678/dogs
enough for
POST GET PUT DELETE
developers to
4 HTTP
migrate
Methods
Bias toward /dogs (not animals)
concrete names Errors
Multiple /dogs.json 8 Status Codes 200 201 304 400 401 403 404 500
formats in URL /dogs.xml
Verbose messages {"msg": "verbose, plain language hints"}
Paginate with ?limit=10&offset=0
limit and offset
Query params ?color=red&state=running
Client Considerations
Partial selection ?fields=name,state
Client does not ?suppress_response_codes=true

Use medial "createdAt": 1320296464 support HTTP
capitalization myObject.createdAt; status codes
/convert?from=EUR&to=CNY&amoun Client does not GET /dogs?method=post
Use verbs for GET /dogs
non-resource t=100 support HTTP
GET /dogs?method=put
requests methods
GET /dogs?method=delete
Search /search?q=happy%2Blabrador Complement API 1. JavaScript
with SDK and code 2. …
DNS api.foo.com 3. …
developers.foo.com libraries

How do we get started with our API?

Build an API Model

http://www.flickr.com/photos/brent_nashville/2156695472/in/photostream/

Don’t Go Cowboy

http://www.flickr.com/photos/theory/3364213389/in/photostream/

Twitter Streaming API
Authorization: Basic aWhlYXJ0OmFwaXM=

Amazon Web Services API
Authorization: AWS
AKIAIOSFODNN7EXAMPLE:frJIUNo//yllqDzg=

Google API
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg

OAuth2
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg

How do approach message design?

Support multiple formats JSON and XML

How do we represent single items?

Twitter Foursquare Instagram
{ { {
"created_at": "Thu Jan 10 08:44:59 "meta": {…}, "meta": {…},
+0000 2013", "notifications": […], "data": {}
"id": 289291736440791040, "response": {} }
"id_str": "289291736440791040", }
"text": "@landlessness here's one
for you: 50-year plan to fix
Detroitnnhttp://t.co/kJ2l1FZv",
"source": "<a
href="http://twitter.com/download/andr
oid" rel="nofollow">Twitter for
Android</a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": 41020312,
"in_reply_to_user_id_str":
"41020312",
"in_reply_to_screen_name":
"landlessness",
"user": {…},
"geo": {…},
"coordinates": {…},
"place": {…},
"contributors”:{…},
"retweet_count": 0,
"entities": {…},
"favorited": false,
"retweeted": false,
"possibly_sensitive": false
}

21

{ { {
"created_at": "Thu Jan 10 08:44:59 "meta": {…}, "meta": {…},
+0000 2013", "notifications": […], "data": {
"id": 289291736440791040, "response": { "attribution": {…},
"id_str": "289291736440791040", "checkin": { "type": "image",
"text": "@landlessness here's one "id": "50eeff78e4b0f8e9624ea5f8", "location": {…},
for you: 50-year plan to fix "createdAt": 1357840248, "comments": {…},
Detroitnnhttp://t.co/kJ2l1FZv", "type": "checkin", "filter": "Sierra",
"source": "<a "shout": "Pharmacy #DRUGS!!! "created_time": "1357826573",
href="http://twitter.com/download/andr #ToothPulled :(", "link":
oid" rel="nofollow">Twitter for "timeZone": "America/Detroit", "http://instagr.am/p/UTk5Xut3gN/",
Android</a>", "timeZoneOffset": -300, "likes": {…},
"truncated": false, "user": {…}, "images": {…},
"in_reply_to_status_id": null, "venue": {…}, "caption": {…},
"in_reply_to_status_id_str": null, "source": {…} "user_has_liked": false,
"in_reply_to_user_id": 41020312, } "id": "365798266911553549_3573549",
"in_reply_to_user_id_str": } "user": {…}
"41020312", } }
"in_reply_to_screen_name": }
"landlessness",
"user": {…},
"geo": {…},
"coordinates": {…},
"place": {…},
"retweet_count": 0,
"entities": {…},
"favorited": false,
"retweeted": false,
}

22

Take the best of Foursquare and Instagram
{
"meta": {…},
"dog": {…}
"notifications": […],
}

23

How do we represent collections?

[ { {
{ "meta": {…}, "meta": {…},
"created_at": "Thu Jan 10 08:44:59 "notifications": […], "data": [
+0000 2013", "response": { {
"id": 289291736440791040, "recent": [ "attribution": {…},
"id_str": "289291736440791040", { "type": "image",
"text": "@landlessness here's one "id": "50eeff78e4b0f8e9624ea5f8", "location": {…},
for you: 50-year plan to fix "createdAt": 1357840248, "comments": {…},
Detroitnnhttp://t.co/kJ2l1FZv", "type": "checkin", "filter": "Sierra",
"source": "<a "shout": "Pharmacy #DRUGS!!! "created_time": "1357826573",
href="http://twitter.com/download/andr #ToothPulled :(", "link":
oid" rel="nofollow">Twitter for "timeZone": "America/Detroit", "http://instagr.am/p/UTk5Xut3gN/",
Android</a>", "timeZoneOffset": -300, "likes": {…},
"truncated": false, "user": {…}, "images": {…},
"in_reply_to_status_id": null, "venue": {…} "caption": {…},
"in_reply_to_status_id_str": null, }, "user_has_liked": false,
"in_reply_to_user_id": 41020312, {…}, "id": "365798266911553549_3573549",
"in_reply_to_user_id_str": {…}, "user": {…}
"41020312", ] },
"in_reply_to_screen_name": } {…},
"landlessness", } {…}
"user": {…}, ]
"geo": {…}, }
"coordinates": {…}, }
"place": {…},
"retweet_count": 0,
"entities": {…},
"favorited": false,
"retweeted": false,
},
{…},
{…}
]

25

Take the best of Foursquare and Instagram
{
"meta": {…},
"dogs": {…} /* include same info as single */
"notifications": […],
}

26

How do we represent search results?

“ Selecting results is not the same as searching.
-Facebook API

Bing Search Google Custom Search Reddit Search
{ { {
"SearchResponse": { "kind": "customsearch#search", "kind": "Listing",
"Version": "2.2", "url": { "data": {
"Query": { "type": "application/json", "after": "t3_qy342",
"SearchTerms": "sushi" "template": "before": null,
}, "https://www.googleapis.com/customsearch/v1?q={s "children": [
"Web": { earchTerms}…}, {
"Total": 95200000, "queries": { "data": {
"Offset": 0, "request": [ "id": "f605o",
"Results": [ { "num_comments": 943,
{ "title": "Google Custom Search - sushi", "score": 1146,
"Title": "The Sushi FAQ - The ultimate "totalResults": "15000000", "ups": 3110,
guide to sushi and sashimi and how to ...", "searchTerms": "sushi", "downs": 1964,
"Description": "What is sushi?..", "count": 10, "created": 1295553753.0,
"Url": "http://www.sushifaq.com/", "startIndex": 1, "url":
"CacheUrl": } "http://www.reddit.com/r/AskReddit/comments/f605
"http://cc.bingj.com/cache.aspx?q=sushi&d=485519 ] o/this_is_a_long_shot_any_sushi_chefs_need_a_job
0808495712&w=yU8fJS-YPT-f4svREMW2xSa75OoBUAZR", }, _in/",
"DisplayUrl": "www.sushifaq.com", "context": { "author": "jining",
"DateTime": "2013-01-08T15:12:00Z" "title": "Custom Search" }
}, }, },
{ "searchInformation": { {
"Title": "What Is Sushi? - Sushi Guide - "searchTime": 0.314942, "data": {
Eatsushi.com", "formattedSearchTime": "0.31", "id": "c9eng”,
"Description": "Eatsushi.com...", "totalResults": "15000000", "num_comments": 308,
"Url": "formattedTotalResults": "15,000,000" "score": 59,
"http://www.eatsushi.com/whatsushi.asp", }, "ups": 128,
"CacheUrl": "items": [ "downs": 69,
"http://cc.bingj.com/cache.aspx?q=sushi&d=501324 { "created": 1275155900.0,
9854931333&w=ihBzI9k9WbrnwxKcV3n8mOoV97M89K-b", "kind": "customsearch#result", "url":
"DisplayUrl": "title": "Standardized Usage Statistics "http://www.reddit.com/r/IAmA/comments/c9eng/i_a
"www.eatsushi.com/whatsushi.asp", Harvesting Initiative (SUSHI ... - NISO", m_a_sushi_man_ama/",
"DateTime": "2013-01-07T13:51:00Z" "htmlTitle": "u003cbu003eStandardized Usage "saved": false, "is_self": true, "permalink":
} Statistics Harvesting Initiativeu003c/bu003e "/r/IAmA/comments/c9eng/i_am_a_sushi_man_ama/",
] (u003cbu003eSUSHIu003c/bu003e "author": "IAmASushiMan”
} u003cbu003e...u003c/bu003e - NISO", }
} "link": }
} "http://www.niso.org/workrooms/sushi", ]
"displayLink": "www.niso.org", }
"snippet": "The Standardized Usage Statistics }
Harvesting Initiative (SUSHI) Protocol
standard (ANSI/NISO Z39.93-2007) defines an
automated request and response model ...”,

29

(Mostly) Follow Google Custom Search
{
"meta": {
"limit": 1,
"offset": 10,
"totalResults": 15000000,
"query": "sushi",
"searchTime": 0.314942
},
"results": [
{},
{},
{}
]
}

30

Netflix API
<link
href=“http://api-public.netflix.com/catalog/people/100637”
rel=“http://schemas.netflix.com/catalog/person.actor”
title="Elijah Wood”
></link>

GitHub API

"organization": {
"login": "octocat",
"id": 1,
"url": "https://api.github.com/users/octocat",
"type": "Organization”
}

Follow Netflix and the Web Linking spec
<link
href=“http://api-public.netflix.com/catalog/people/100637”
rel=“http://schemas.netflix.com/catalog/person.actor”
title="Elijah Wood”
></link>

GitHub

Form-based API
”actions": [{
“name”: “edit-repo”,
“method”: “PATCH”,
“href”: “https://api.github.com/repos/kevinswiber/siren”,
”fields”: [ { “name”: “name”, “type”: “text” },
{ “name”: “description”, “type”: “text” }
}]

Form-based API
"actions": [{
"name": "edit-repo",
“method”: “PATCH”,
“href”: “https://api.github.com/repos/kevinswiber/siren”,
”fields”: [ { “name”: “name”, “type”: “text” },
{ “name”: “description”, “type”: “text” }
}]

Flickr API (inline)
<item
type="photo”
id="10289”
server="2”
views="47”
faves="0”
more="0">

Dropbox API (/metadata)
{
"size": "225.4KB”,
"rev": "35e97029684fe”,
"bytes": 230783,
"modified": "Tue, 19 Jul 2011 21:55:38 +0000”,
"path": "/Getting_Started.pdf”,
"is_dir": false,
"icon": "page_white_acrobat”,
"root": "dropbox”,
"mime_type": "application/pdf”,
"revision": 220823
}

Include a metadata in responses and consider a dedicated
/meta resource
{
"meta": {
"size": "225.4KB”,
"rev": "35e97029684fe”,
"bytes": 230783,
"modified": "Tue, 19 Jul 2011 21:55:38 +0000”,
"path": "/Getting_Started.pdf”,
"is_dir": false,
"icon": "page_white_acrobat”,
"root": "dropbox”,
"mime_type": "application/pdf”,
"revision": 220823
}
}

39

What can we learn from hypermedia types?

Atom/AtomPub
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>My New Collection</title>
<id>urn:uuid:de46e3a1-e489-41a6-88a6-21e7f0e8e2d8</id>
<updated>2009-06-12T12:13:46Z</updated>
<author>
<name>Daffy</name>
</author>
<summary type="text" />
<content type="application/atom+xml;type=feed"
src="http://example.org/my-new-collection"/>
<link rel="edit”
href="http://example.org/my-new-collection.atom" />
</entry>

XHTML
<ul class=“search user-list”>
<li class=“user”>
<div class="avatar">
<a href="/users/@kevin">
<img class=”user-image" src=”/img/avatar.png" />
</a>
</div>
<div>
<a href=“/users/@kevin” rel=“user messages”>
<span class=“user-name”>@kevin</span>
(<span class="user-text">@kevin</span>)
</a>
</div>
</li>
</ul>

HAL

{
“currentlyProcessing”: 14
“shippedToday”: 20,
“_links”: {
“self”: { “href”: “/orders?page=2” },
“next”: { “href”: “/orders?page=3” },
“prev”: { “href”: “/orders?page=1” }
}
}

Collection+JSON
{ “collection”:
{
“version”: “1.0”,
“href”: “http://example.org/friends”,
“items”: [
“href”: “http://example.org/friends/kevin”,
“data”: [
{“name”: “full-name”, “value”: “Kevin Swiber” }
]
],
“queries”: [
{“rel”: “search”, “href”: “./search”, “data”: [
{“name”: “search”, “value”: “” }
]
}
}

Siren
{
“class”: [“owner”, “vip”],
“properties”: {
“name”: “Kevin”
},
“entities”: [
{
“rel”: [“https://rels.x.io/dog”],
“href”: “https://api.x.io/dogs/1”
}
],
“actions”: [
{
“name”: “adopt”,
“method”: “POST”,
“href”: “https://api.x.io/owners/1/dogs”,
“fields”: [ { “name”: “dog-name”, “type”: “text” } ]
}
],
“links”: [
{ “rel”: [“self”], “href”: “https://api.x.io/owners/1” }
]
}

multipart/form-data
Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name=“caption”

Cool picture of my cat.
--AaB03x
Content-Disposition: form-data; name=“photo”; filename=“catpajamas.jpg”
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

…contents of catpajamas.jpg…
--AaB03x

Inline Base64 Encoding
POST /photos
{
“caption”: “Cool picture of my cat.”
“photo”: “RHVkZSwgbXkgY2F0IGhhcyB0aGUgYmVzdCBwYWphbWFzLg==”
}

2-Step Process
POST /photos
{
“caption”: “Cool picture of my cat.”
}

PUT /photos/1234/data
Content-Type: image/jpeg
Content-Length: 240
Content-Transfer-Encoding: binary

…binary content…

Opt for multipart/form-data.
Be consistent.

Expiration

200 OK
Cache-Control: private, max-age=2592000

ETags

GET /dogs/1
ETag: “a7D92kda94aisdfG”

GET /dogs/1
If-None-Match: “a7D92kda94aisdfG”

Last-Modified

GET /dogs/1
Last-Modified: Thu, 10 Jan 2013 19:43:31 GMT

GET /dogs/1
If-Modified-Since: Thu, 10 Jan 2013 19:43:31 GMT

Yes. Follow LinkedIn’s lead.

application/x-www-form-urlencoded

breed=Dachshund&name=Hotdog&age=2

application/xml

<dog>
<breed>Dachshund</breed>
<name>Hotdog</name>
<age>2</age>
</dog>

application/json

{
“breed”: “Dachshund”,
“name”: “Hotdog”,
“age”: 2
}

Favor application/x-www-form-urlencoded data.

How do we handle transactions?

Create a Transaction
POST /carts
…
201 Created
Location: /carts/1

Add Items
POST /carts/1/items/
{ “productId”: “mittens123”, “quantity”: 1 }
…
201 Created
Location: /cartItems/1234

Commit the Transaction
POST /carts/1
{ “message”: “checkout” }
…
200 OK

Summary
• Checkout previous editions for URI design
• Start with API modeling
• Use OAuth for security
• Good message design is for developers
• Learn from hypermedia specs
• More on transactions later

THANK YOU
Subscribe to API webinars at:
youtube.com/apigee

THANK YOU
Questions and ideas to:
groups.google.com/group/api-craft

THANK YOU
Contact us at:

@landlessness
brian@apigee.com

@kevinswiber
kswiber@apigee.com

@apigee

API Design - 3rd Edition

In this document