WYNN NETHERLAND User Experience Patterns for APIs

Howdy!

Wynn Netherland My name is

No content

No content

No content

.com

No content

No content

I write API wrappers

No content

No content

UX Patterns for APIs and anti-patterns ^

Support curling PATTERN

curl -i https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT { "following": 212, "type": "User", "html_url": "https://github.com/defunkt", "location": "San Francisco", "hireable": true,

curl -i -u pengwynn \ https://api.github.com/user

curl -i -u pengwynn \ https://api.github.com/user include response headers

curl -i -u pengwynn \ https://api.github.com/user use Basic Auth, prompt for password

Security mazes ANTI-PATTERN

No content

OAuth is painful. OAuth2 hurts less.

No content

Insane URLs ANTI-PATTERN

http://sandbox.api.shopping.com/publisher/ 3.0/rest/GeneralSearch? hybridSortType=relevance&productSortType=r elevance&offerSortType=store- name&productReviewSortType=review-date

http://maps.googleapis.com/maps/api/ staticmap?center=Brooklyn+Bridge,New +York,NY&zoom=13&size=600x300&maptype=road map&markers=color:blue%7Clabel:S %7C40.702147,-74.015794&markers=color:gree n%7Clabel:G%7C40.711614,-74.012318 &markers=color:red%7Ccolor:red%7Clabel:C %7C40.718217,-73.998284&sensor=false

Maximize the payload PATTERN

{ "uri": "/pengwynn/githubbers", "name": "GitHubbers", "full_name": "@pengwynn/githubbers", "description": "", "mode": "public", "user": { "id": 14100886, "favourites_count": 275, "profile_image_url": "http://a0.twimg.com/profile_ima...", "profile_background_tile": false, "profile_sidebar_fill_color": "DDEEF6", "verified": false, "location": "Denton, TX", "utc_offset": -21600, "name": "Wynn Netherland", "lang": "en", "is_translator": false, "default_profile": true, "profile_background_color": "C0DEED", "protected": false, "contributors_enabled": false, "time_zone": "Central Time (US & Canada)", "profile_background_image_url": "http://a0.twimg.com/images/themes/...", "profile_link_color": "0084B4", "description": "Christian, husband, father, GitHubber, Co-host...", "geo_enabled": true, "listed_count": 388, "show_all_inline_media": true, "notifications": false, "id_str": "14100886", "statuses_count": 7178, "profile_image_url_https": "https://si0.twimg.com/profile_images/2221455972/

{ "uri": "/pengwynn/githubbers", "name": "GitHubbers", "full_name": "@pengwynn/githubbers", "description": "", "mode": "public", "user": { "id": 14100886, "favourites_count": 275, "profile_image_url": "http://a0.twimg.com/profile_ima...", "profile_background_tile": false, "profile_sidebar_fill_color": "DDEEF6", "verified": false, "location": "Denton, TX", "utc_offset": -21600, "name": "Wynn Netherland", "lang": "en", "is_translator": false, "default_profile": true, "profile_background_color": "C0DEED", "protected": false, "contributors_enabled": false, "time_zone": "Central Time (US & Canada)", "profile_background_image_url": "http://a0.twimg.com/images/themes/...", "profile_link_color": "0084B4", "description": "Christian, husband, father, GitHubber, Co-host...", "geo_enabled": true, "listed_count": 388, "show_all_inline_media": true, "notifications": false, "id_str": "14100886", "statuses_count": 7178, "profile_image_url_https": "https://si0.twimg.com/profile_images/2221455972/ Full User object

Rock the cache PATTERN

curl -I https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT

curl -I https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT

curl -I https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT Cache policy

curl -I https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT Fingerprint

curl -I \ -H 'If-None-Match:"ef742caec0c19e2169ffb05e7d200d17" \ https://api.github.com/users/defunkt HTTP/1.1 304 Not Modified Server: nginx Date: Wed, 12 Sep 2012 15:51:39 GMT Connection: keep-alive Status: 304 Not Modified X-RateLimit-Limit: 5000 X-Content-Type-Options: nosniff Vary: Accept ETag: "ef742caec0c19e2169ffb05e7d200d17" X-RateLimit-Remaining: 4997 Last-Modified: Wed, 12 Sep 2012 01:38:14 GMT Cache-Control: public, s-maxage=60, max-age=60

curl -H 'If-None-Match:"ef742caec0c19e2169ffb05e7d200d17" \ https://api.github.com/users/defunkt HTTP/1.1 304 Not Modified Server: nginx Date: Wed, 12 Sep 2012 15:51:39 GMT Connection: keep-alive Status: 304 Not Modified X-RateLimit-Limit: 5000 X-Content-Type-Options: nosniff Vary: Accept ETag: "ef742caec0c19e2169ffb05e7d200d17" X-RateLimit-Remaining: 4997 Last-Modified: Wed, 12 Sep 2012 01:38:14 GMT Cache-Control: public, s-maxage=60, max-age=60

$ curl -i https://api.github.com/user HTTP/1.1 200 OK Cache-Control: private, max-age=60 ETag: "644b5b0155e6404a9cc4bd9d8b1ae730" Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 200 OK Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996 $ curl -i https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT" HTTP/1.1 304 Not Modified Cache-Control: private, max-age=60 Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 304 Not Modified Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996 $ curl -i https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"' HTTP/1.1 304 Not Modified Cache-Control: private, max-age=60 ETag: "644b5b0155e6404a9cc4bd9d8b1ae730" Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 304 Not Modified Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996

Dogfood it PATTERN

Build something meaningful with your API.

Build something meaningful with your API. Janky

Build something meaningful with your API. Janky Heaven

Build something meaningful with your API. Janky Heaven Monitors

Build something meaningful with your API. Janky Team Heaven Monitors

Build something meaningful with your API. Janky Team Hire Heaven Monitors

Build something meaningful with your API. Janky Team Hire Heaven Monitors The Setup™

Build something meaningful with your API. Janky Team Hire Heaven Monitors The Setup™ Graph Store

How GitHub uses the GitHub API.

How GitHub uses the GitHub API. AuthN

How GitHub uses the GitHub API. AuthN AuthZ

How GitHub uses the GitHub API. AuthN AuthZ Merging

How GitHub uses the GitHub API. AuthN AuthZ Merging Commit Status

How GitHub uses the GitHub API. AuthN AuthZ Merging Commit Status GFM

Oh, and native apps.

Oh, and native apps. GitHub for Mac

Oh, and native apps. GitHub for Mac GitHub for Windows

PATTERN Use HTTP status codes

HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT { "error_code": 1234, "error": "User not found" }

HTTP/1.1 404 Not Found Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 404 Not Found

Confusing header with body ANTI-PATTERN

Harsh rate limits ANTI-PATTERN

$ curl -i https://api.github.com/users/ whatever? client_id=xxxxxxxxxxxxxx&client_secret=yyy yyyyyyyyyyyyyyyyyy HTTP/1.1 200 OK Status: 200 OK X-RateLimit-Limit: 12500 X-RateLimit-Remaining: 11966

Announce breaking changes PATTERN

No content

Make documentation obvious PATTERN

No content

No content

No content

No content

Create awesome guides PATTERN

No content

No content

No content

Consoles PATTERN

No content

No content

ANTI-PATTERN Endless terms of service changes

Inconsistency ANTI-PATTERN

POST /gists/:id/fork POST /repos/:user/:repo/merges

Fast, transparent support PATTERN

No content

Free samples PATTERN

No content

Mashup friendly PATTERN

JSONP

$ curl https://api.github.com?callback=foo foo({ "meta": { "status": 200, "X-RateLimit-Limit": "5000", "X-RateLimit-Remaining": "4966", "Link": [ // pagination headers and other links ["https://api.github.com?page=2", {"rel": "next"}] ] }, "data": { // the data } })

CORS

$ curl -i https://api.github.com \ -H "Origin: http://calendaraboutnothing.com" HTTP/1.1 302 Found Access-Control-Allow-Origin: http://calendaraboutnothing.com Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X- RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes Access-Control-Allow-Credentials: true

$ curl -i https://api.github.com \ -H "Origin: http://calendaraboutnothing.com" -X OPTIONS HTTP/1.1 204 No Content Access-Control-Allow-Origin: http://calendaraboutnothing.com Access-Control-Allow-Headers: Authorization, X-Requested-With Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X- RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes Access-Control-Max-Age: 86400 Access-Control-Allow-Credentials: true

Streaming PATTERN

Persistent HTTP

Updates as they happen

No content

Thanks!