![Page 1: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/1.jpg)
7 — Web API Design
From Code to Product gidgreen.com/course
![Page 2: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/2.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Resources
From Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com/course
![Page 3: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/3.jpg)
Application Programming Interface
“a set of functions and procedures that allow the creation of applications which access the features or data of an operating system, application, or other service.”
— Oxford English Dictionary
“An interface or go-between that enables a software program to interact with other software.” — Investopedia
From Code to Product Lecture 7 — Web API Design — Slide 3 gidgreen.com/course
![Page 4: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/4.jpg)
Types of API
• Programming language libraries, e.g. C – malloc(), printf(), strcpy()
• Operating systems, e.g. Android – findViewById(R.id.search).setText("");
• Plug-in APIs, e.g. NPAPI for browsers – NPError NP_Initialize(…)
• Web APIs, e.g. Yahoo! BOSS – http://yboss.yahooapis.com/ysearch/web?q=API
From Code to Product Lecture 7 — Web API Design — Slide 4 gidgreen.com/course
![Page 5: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/5.jpg)
Web APIs
• Same infrastructure as websites – Request—Response over HTTP – Open and exposed to the world
• Textual request/response – URLs in, JSON/XML out (generally)
• Many simply wrap web requests… – e.g. search APIs, Twitter posting
• …but many go far beyond
From Code to Product Lecture 7 — Web API Design — Slide 5 gidgreen.com/course
![Page 6: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/6.jpg)
Example: Facebook Graph API
From Code to Product Lecture 7 — Web API Design — Slide 6 gidgreen.com/course
![Page 7: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/7.jpg)
Amazon Product Advertising API
From Code to Product Lecture 7 — Web API Design — Slide 7 gidgreen.com/course
![Page 8: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/8.jpg)
Twitter REST API
From Code to Product Lecture 7 — Web API Design — Slide 8 gidgreen.com/course
![Page 9: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/9.jpg)
Growth in Web APIs
From Code to Product Lecture 7 — Web API Design — Slide 9 gidgreen.com/course
![Page 10: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/10.jpg)
API Billionaires’ Club
From Code to Product Lecture 7 — Web API Design — Slide 10 gidgreen.com/course
http
://b
log.
prog
ram
mab
lew
eb.c
om/2
012/
05/2
3/w
hich
-api
s-ar
e-ha
ndlin
g-bi
llion
s-of
-req
uest
s-pe
r-da
y/
![Page 11: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/11.jpg)
Why offer an API?
• Avoid (control) scraping • Develop partnerships – “Business development 2.0”
• Increase revenue (if paid) • Externalize innovation – Copy the best?
• Customer lock-in through integration
From Code to Product Lecture 7 — Web API Design — Slide 11 gidgreen.com/course
![Page 12: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/12.jpg)
Business questions
• What is our goal for the API? – How does it contribute to business?
• Free vs paid? – Revenue generation vs marketing
• Who will use it? – Aim at those developers’ success
• What do they want to do with it? – Can our competitors make use of it?
From Code to Product Lecture 7 — Web API Design — Slide 12 gidgreen.com/course
![Page 13: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/13.jpg)
API-focused companies: Stripe
From Code to Product Lecture 7 — Web API Design — Slide 13 gidgreen.com/course
![Page 14: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/14.jpg)
API-focused companies: Zencoder
From Code to Product Lecture 7 — Web API Design — Slide 14 gidgreen.com/course
![Page 15: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/15.jpg)
API-only companies: SendGrid
From Code to Product Lecture 7 — Web API Design — Slide 15 gidgreen.com/course
![Page 16: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/16.jpg)
API-only companies: Twilio
From Code to Product Lecture 7 — Web API Design — Slide 16 gidgreen.com/course
![Page 17: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/17.jpg)
API vs licensing code
• Better business model – Recurring revenue (by usage) – Suits small and large clients
• Easier to maintain – No need for “releases” – Controlled environment
• Keep control over IP • But it’s a serious operation – Risk of downtime (SLAs?)
From Code to Product Lecture 7 — Web API Design — Slide 17 gidgreen.com/course
![Page 18: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/18.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Resources
From Code to Product Lecture 7 — Web API Design — Slide 18 gidgreen.com/course
![Page 19: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/19.jpg)
REST
• Representational State Transfer – Most popular design model for Web APIs
• Entities (“resources”) = URLs • Actions = HTTP commands – GET, POST, PUT, DELETE
• Resources are self-descriptive • No hidden server-side state • (UI Principles applied to developers!) From Code to Product Lecture 7 — Web API Design — Slide 19 gidgreen.com/course
![Page 20: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/20.jpg)
HTTP request example PUT /api/dogs/3 HTTP/1.1 Host: dog-db.com Content-Type: application/x-www-form-urlencoded Content-Length: 21 Request data...
From Code to Product Lecture 7 — Web API Design — Slide 20 gidgreen.com/course
HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Content-Length: 94 Response data…
![Page 21: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/21.jpg)
REST GET Example 1
GET http://dog-db.com/api/dogs
[
{ id:1, name:"Fido" },
{ id:2, name:"Rover" },
{ id:3, name:"Spot" },
{ id:4, name:"Fluffy" },
]
From Code to Product Lecture 7 — Web API Design — Slide 21 gidgreen.com/course
![Page 22: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/22.jpg)
REST GET Example 2
GET http://dog-db.com/api/dogs/3
{
id:3,
name:"Spot",
dob:"2009-05-21",
type:"spaniel",
photo:"http://dog-db/images/…
From Code to Product Lecture 7 — Web API Design — Slide 22 gidgreen.com/course
![Page 23: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/23.jpg)
Expressing relationships
{ id:3,
name:"Spot", dob:"2009-05-21",
owner:{
id:16, name:"Sam",
url:"http://dog-db.com/api/owners/16" }
…
From Code to Product Lecture 7 — Web API Design — Slide 23 gidgreen.com/course
![Page 24: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/24.jpg)
HTTP command
Database operation /dogs /dogs/3
GET Read List all dogs Get dog details
POST Create Create new dog —
PUT Update — Update detail/s
DELETE Delete Delete all dogs Delete this dog
REST as CRUD
From Code to Product Lecture 7 — Web API Design — Slide 24 gidgreen.com/course
![Page 25: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/25.jpg)
REST PUT Example
PUT http://dog-db/api/dogs/3 name=Fifi&type=poodle
{
id:3,
name:”Fifi",
dob:"2009-05-21",
type:”poodle”,
From Code to Product Lecture 7 — Web API Design — Slide 25 gidgreen.com/course
![Page 26: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/26.jpg)
Rules for REST actions
• GET does not change server state – Allows caching, prefetching – Like requesting web page
• PUT and DELETE are “idempotent” – Repeated calls don’t matter
• POST can change server state each time – Classic example: transfer money – Like submitting web form
From Code to Product Lecture 7 — Web API Design — Slide 26 gidgreen.com/course
![Page 27: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/27.jpg)
Choosing REST URLs
• Stick to plural forms – /dogs → /dogs/3 not /dog/3
• Avoid abstractions – /dogs/3 better than /entities/3
• If multiple return types: – /dogs/3?type=json – /dogs/3.json
• Consistency is king!
From Code to Product Lecture 7 — Web API Design — Slide 27 gidgreen.com/course
![Page 28: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/28.jpg)
More URL best practices
• Pagination of results – ?start=20&count=10
• Subset of fields – ?fields=id,name,owner,type
• API calls not on resources – GET /api/search?q=... – GET /api/convert?from=km&to=inch&value=0.63
From Code to Product Lecture 7 — Web API Design — Slide 28 gidgreen.com/course
![Page 29: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/29.jpg)
Other protocols
• Simple Object Access Protocol (SOAP) – XML-based + lots of extra cruft – Hard to read and write manually – Formalization and discovery via WSDL
• XML-Remote Procedure Call (XML-RPC) – Simpler precursor to SOAP – Based on functions, e.g. getDogName()
• Neither uses URLs for entities
From Code to Product Lecture 7 — Web API Design — Slide 29 gidgreen.com/course
![Page 30: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/30.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Resources
From Code to Product Lecture 7 — Web API Design — Slide 30 gidgreen.com/course
![Page 31: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/31.jpg)
Important data types
• String • Number • Boolean • Date/time • Null/nil • Binary large objects (BLOBs) • Array = unlabeled ordered list • Object = labeled (ordered) list
From Code to Product Lecture 7 — Web API Design — Slide 31 gidgreen.com/course
Scalars
![Page 32: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/32.jpg)
Extensible Markup Language (XML)
<dogs>
<dog id="3"> <name>Spot</name>
<age>7</age>
<type></type>
<owner id="16">
<name>Sam</name> </owner>
<collar>true</collar>
</dog>
<dog id="4">
...
From Code to Product Lecture 7 — Web API Design — Slide 32 gidgreen.com/course
ü User friendly ü Looks like HTML ⨯ Wordy ⨯ Elements vs
attributes ⨯ Implicit typing ⨯ "123" ⨯ Array of one
![Page 33: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/33.jpg)
RSS 2.0 (see also: Atom) <rss version="2.0">
<channel>
<title>Dog Tales</title>
<description>Stories about dogs</description>
<link>http://dog-tales.com/</link>
<item>
<title>Cat chasing</title>
<description>A dog ran after a cat</description>
<link>http://dog-tales.com/</link> <pubDate>Thu, 09 May 2013 16:45:00 +0000</pubDate>
</item>
<item>
...
From Code to Product Lecture 7 — Web API Design — Slide 33 gidgreen.com/course
![Page 34: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/34.jpg)
Javascript Object Notation (JSON)
[
{ id:3,
name:"Spot",
age:7,
type:null,
owner:{id:16,name:"Sam"}, collar:true,
},
{
id:4,
...
From Code to Product Lecture 7 — Web API Design — Slide 34 gidgreen.com/course
ü Compact ü Explicit types ü [] vs {} ü Javascript-ish ü JSONP for
web access ⨯ Feels like
programming
![Page 35: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/35.jpg)
Urlencoding
• URL parameters • Multifield forms (PUT/POST)
From Code to Product Lecture 7 — Web API Design — Slide 35 gidgreen.com/course
http://dog-tales.com/
![Page 36: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/36.jpg)
BLOBs (rich media)
• Raw delivery – Can’t be combined with other data – For HTTP use MIME to identify
• Provide URL (string) – Separate request to retrieve
• Base64 encoding – Inflates size by 33% – Standard method for web forms
From Code to Product Lecture 7 — Web API Design — Slide 36 gidgreen.com/course
![Page 37: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/37.jpg)
Error reporting
• Use HTTP response code – Allow suppression, e.g. for Flash
• Error in response: {
http-code:401, error-code:-329,
error-message:"Invalid API key",
error-help:"http://dog-db.com/docs errors/-329.html”
From Code to Product Lecture 7 — Web API Design — Slide 37 gidgreen.com/course
![Page 38: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/38.jpg)
HTTP response codes
From Code to Product Lecture 7 — Web API Design — Slide 38 gidgreen.com/course
HTTP code Meaning
200 OK
4xx Bad request (client’s fault)
5xx Failed request (server’s fault)
401 Unauthorized request
404 Resource not found
500 Internal error (bug)
503 Server overloaded
![Page 39: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/39.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Resources
From Code to Product Lecture 7 — Web API Design — Slide 39 gidgreen.com/course
![Page 40: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/40.jpg)
Simple HTTP Authentication
GET /api/dogs/?appID=29838&key=k234nb3bf89 Host: dog-db.com GET /api/dogs/ Host: dog-db.com Authorization: Basic QWxhZGRpbjpvcGc2FtZQ==
From Code to Product Lecture 7 — Web API Design — Slide 40 gidgreen.com/course
ü Trivial for developers ⨯ Visible to intermediaries
ü https can solve this
![Page 41: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/41.jpg)
Signing API calls
• Client and server share secret key • Signature is hash (one-way function) of: – Request – Parameters (alphabetical order) – Secret key
• Best practice: multiple keys per user – Users can disable some applications
• Problem: replay attacks
From Code to Product Lecture 7 — Web API Design — Slide 41 gidgreen.com/course
![Page 42: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/42.jpg)
OAuth 1.0
• Standard for digitally signing API calls • Permits delegation – User grants temporary access to API for them
• Prevents replay attacks – Via ‘nonce’ = number used once
• Popular industry standard – Dropbox, Evernote, Flickr, Twitter
• See also: OAuth 2.0
From Code to Product Lecture 7 — Web API Design — Slide 42 gidgreen.com/course
![Page 43: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/43.jpg)
Rate limiting
• Per IP address, but… – Proxy networks e.g. Tor – Temporary cloud instances
• Per API key, but… – Multiple key signups
• Per queried entity • Based on (API) server load • Charging solves everything…
From Code to Product Lecture 7 — Web API Design — Slide 43 gidgreen.com/course
![Page 44: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/44.jpg)
Final comments on security
• Do not trust clients – All input must be sanitized
• Clients must store key – So desktop/mobile apps hackable
• You can’t take back data – Limit scope of responses
• Don’t reinvent the wheel – Save developers time
From Code to Product Lecture 7 — Web API Design — Slide 44 gidgreen.com/course
![Page 45: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/45.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Resources
From Code to Product Lecture 7 — Web API Design — Slide 45 gidgreen.com/course
![Page 46: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/46.jpg)
Maintenance issues
• Downtime • Versioning • Scaling • Monitoring • Logging
From Code to Product Lecture 7 — Web API Design — Slide 46 gidgreen.com/course
![Page 47: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/47.jpg)
Downtime
• Developers test then deploy – When you go down, they go down
• So avoid at all costs by: – Monitoring – Versioning
• If unavoidable then: – Do it on the weekend – Give advanced notice
From Code to Product Lecture 7 — Web API Design — Slide 47 gidgreen.com/course
![Page 48: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/48.jpg)
API status
From Code to Product Lecture 7 — Web API Design — Slide 48 gidgreen.com/course
![Page 49: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/49.jpg)
Versioning
GET http://dog-db.com/api/v1/dogs/
• Version at start of URL • v1 then v2 — no v1.1 – Makes compatibility clear
• Maintain one version back • It’s still a failure – Add URLs/parameters instead
From Code to Product Lecture 7 — Web API Design — Slide 49 gidgreen.com/course
![Page 50: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/50.jpg)
Scaling
• Usage volumes can surprise you – You’re serving software, not people – Small number of heavy users – Very peaky traffic
• Caching is your friend • Drop expensive requests under load • Slow response better than none • Separate domain: api.dog-db.com
From Code to Product Lecture 7 — Web API Design — Slide 50 gidgreen.com/course
![Page 51: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/51.jpg)
Monitoring
• Volume of API calls • Popular calls • Response time • Error rates • Active developers – Hyperactive developers
• Revenue (+indirect) vs costs
From Code to Product Lecture 7 — Web API Design — Slide 51 gidgreen.com/course
![Page 52: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/52.jpg)
Monitoring made public
From Code to Product Lecture 7 — Web API Design — Slide 52 gidgreen.com/course
![Page 53: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/53.jpg)
Logging
• Log everything – Incoming requests – Outgoing response – Response time
• To enable… – Bug resolution – Abuse forensics – Deeper (offline) analytics
From Code to Product Lecture 7 — Web API Design — Slide 53 gidgreen.com/course
![Page 54: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/54.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Conclusion
From Code to Product Lecture 7 — Web API Design — Slide 54 gidgreen.com/course
![Page 55: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/55.jpg)
Documentation
• Reference • Examples • API explorer • Language libraries • Example apps • Discussion forum • (and support)
From Code to Product Lecture 7 — Web API Design — Slide 55 gidgreen.com/course
![Page 56: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/56.jpg)
Reference: security
From Code to Product Lecture 7 — Web API Design — Slide 56 gidgreen.com/course
![Page 57: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/57.jpg)
Reference: URLs
From Code to Product Lecture 7 — Web API Design — Slide 57 gidgreen.com/course
![Page 58: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/58.jpg)
Reference: input parameters
From Code to Product Lecture 7 — Web API Design — Slide 58 gidgreen.com/course
![Page 59: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/59.jpg)
For each input parameter
• Name of parameter • Explanation/meaning • Possible values/range • Example values • Optional or required? – Default value if optional
From Code to Product Lecture 7 — Web API Design — Slide 59 gidgreen.com/course
![Page 60: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/60.jpg)
Reference: output fields
From Code to Product Lecture 7 — Web API Design — Slide 60 gidgreen.com/course
![Page 61: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/61.jpg)
Reference: response codes
From Code to Product Lecture 7 — Web API Design — Slide 61 gidgreen.com/course
![Page 62: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/62.jpg)
Examples
From Code to Product Lecture 7 — Web API Design — Slide 62 gidgreen.com/course
![Page 63: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/63.jpg)
API explorer
From Code to Product Lecture 7 — Web API Design — Slide 63 gidgreen.com/course
![Page 64: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/64.jpg)
Language libraries
From Code to Product Lecture 7 — Web API Design — Slide 64 gidgreen.com/course
ü Developers save time
ü Get fewer bad API calls
⨯ You must learn many languages
⨯ Maintenance
![Page 65: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/65.jpg)
Example apps
From Code to Product Lecture 7 — Web API Design — Slide 65 gidgreen.com/course
![Page 66: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/66.jpg)
Discussion forum
From Code to Product Lecture 7 — Web API Design — Slide 66 gidgreen.com/course
![Page 67: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/67.jpg)
Lecture 7
• Introduction • REST • Data formats • Security • Maintenance • Documentation • Conclusion
From Code to Product Lecture 7 — Web API Design — Slide 67 gidgreen.com/course
![Page 68: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/68.jpg)
Things to avoid
• Lengthy signup process • Exposing raw/ugly data • Complex security model • Breaking backwards compatibility • Inaccurate documentation • Multi-call operations (“chatty APIs”) • Developer frustration
From Code to Product Lecture 7 — Web API Design — Slide 68 gidgreen.com/course
![Page 69: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/69.jpg)
Books
From Code to Product Lecture 7 — Web API Design — Slide 69 gidgreen.com/course
![Page 70: 7 — Web API Design - Gideon · PDF fileFrom Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com ... • Programming language libraries, e.g ... Amazon Product Advertising](https://reader034.vdocuments.net/reader034/viewer/2022051508/5aa9207e7f8b9a77188c6a05/html5/thumbnails/70.jpg)
Resources and services
From Code to Product Lecture 7 — Web API Design — Slide 70 gidgreen.com/course