7 Web API Design From Code to Product gidgreen.com/course Lecture - - PowerPoint PPT Presentation

▶
7 web api design
SMART_READER_LITE
LIVE PREVIEW

7 Web API Design From Code to Product gidgreen.com/course Lecture - - PowerPoint PPT Presentation

Mar 23, 2024 950 likes •1.67k views

7 Web API Design From Code to Product gidgreen.com/course Lecture 7 Introduction REST Data formats Security Maintenance Documentation Resources From Code to Product Lecture 7 Web API Design Slide 2

slide-1
SLIDE 1

7 — Web API Design

From Code to Product gidgreen.com/course

slide-2
SLIDE 2

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Resources

From Code to Product Lecture 7 — Web API Design — Slide 2 gidgreen.com/course

slide-3
SLIDE 3

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

slide-4
SLIDE 4

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

slide-5
SLIDE 5

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

slide-6
SLIDE 6

Example: Facebook Graph API

From Code to Product Lecture 7 — Web API Design — Slide 6 gidgreen.com/course

slide-7
SLIDE 7

Amazon Product Advertising API

From Code to Product Lecture 7 — Web API Design — Slide 7 gidgreen.com/course

slide-8
SLIDE 8

Twitter REST API

From Code to Product Lecture 7 — Web API Design — Slide 8 gidgreen.com/course

slide-9
SLIDE 9

Growth in Web APIs

From Code to Product Lecture 7 — Web API Design — Slide 9 gidgreen.com/course

slide-10
SLIDE 10

API Billionaires’ Club

From Code to Product Lecture 7 — Web API Design — Slide 10 gidgreen.com/course

http://blog.programmableweb.com/2012/05/23/ which-apis-are-handling-billions-of-requests-per-day/

slide-11
SLIDE 11

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

slide-12
SLIDE 12

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

slide-13
SLIDE 13

API-focused companies: Stripe

From Code to Product Lecture 7 — Web API Design — Slide 13 gidgreen.com/course

slide-14
SLIDE 14

API-focused companies: Zencoder

From Code to Product Lecture 7 — Web API Design — Slide 14 gidgreen.com/course

slide-15
SLIDE 15

API-only companies: SendGrid

From Code to Product Lecture 7 — Web API Design — Slide 15 gidgreen.com/course

slide-16
SLIDE 16

API-only companies: Twilio

From Code to Product Lecture 7 — Web API Design — Slide 16 gidgreen.com/course

slide-17
SLIDE 17

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

slide-18
SLIDE 18

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Resources

From Code to Product Lecture 7 — Web API Design — Slide 18 gidgreen.com/course

slide-19
SLIDE 19

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

slide-20
SLIDE 20

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…

slide-21
SLIDE 21

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

slide-22
SLIDE 22

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

slide-23
SLIDE 23

Expressing relationships

{ id:3, name:"Spot", dob:"2009-05-21",

  • wner:{

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

slide-24
SLIDE 24

HTTP command Database

  • peration

/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

slide-25
SLIDE 25

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

slide-26
SLIDE 26

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

slide-27
SLIDE 27

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

slide-28
SLIDE 28

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

slide-29
SLIDE 29

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

slide-30
SLIDE 30

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Resources

From Code to Product Lecture 7 — Web API Design — Slide 30 gidgreen.com/course

slide-31
SLIDE 31

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

slide-32
SLIDE 32

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

slide-33
SLIDE 33

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

slide-34
SLIDE 34

Javascript Object Notation (JSON)

[ { id:3, name:"Spot", age:7, type:null,

  • wner:{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

slide-35
SLIDE 35

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/

slide-36
SLIDE 36

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

slide-37
SLIDE 37

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

slide-38
SLIDE 38

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

slide-39
SLIDE 39

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Resources

From Code to Product Lecture 7 — Web API Design — Slide 39 gidgreen.com/course

slide-40
SLIDE 40

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

slide-41
SLIDE 41

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

slide-42
SLIDE 42

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

slide-43
SLIDE 43

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

slide-44
SLIDE 44

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

slide-45
SLIDE 45

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Resources

From Code to Product Lecture 7 — Web API Design — Slide 45 gidgreen.com/course

slide-46
SLIDE 46

Maintenance issues

  • Downtime
  • Versioning
  • Scaling
  • Monitoring
  • Logging

From Code to Product Lecture 7 — Web API Design — Slide 46 gidgreen.com/course

slide-47
SLIDE 47

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

slide-48
SLIDE 48

API status

From Code to Product Lecture 7 — Web API Design — Slide 48 gidgreen.com/course

slide-49
SLIDE 49

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

slide-50
SLIDE 50

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

slide-51
SLIDE 51

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

slide-52
SLIDE 52

Monitoring made public

From Code to Product Lecture 7 — Web API Design — Slide 52 gidgreen.com/course

slide-53
SLIDE 53

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

slide-54
SLIDE 54

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Conclusion

From Code to Product Lecture 7 — Web API Design — Slide 54 gidgreen.com/course

slide-55
SLIDE 55

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

slide-56
SLIDE 56

Reference: security

From Code to Product Lecture 7 — Web API Design — Slide 56 gidgreen.com/course

slide-57
SLIDE 57

Reference: URLs

From Code to Product Lecture 7 — Web API Design — Slide 57 gidgreen.com/course

slide-58
SLIDE 58

Reference: input parameters

From Code to Product Lecture 7 — Web API Design — Slide 58 gidgreen.com/course

slide-59
SLIDE 59

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

slide-60
SLIDE 60

Reference: output fields

From Code to Product Lecture 7 — Web API Design — Slide 60 gidgreen.com/course

slide-61
SLIDE 61

Reference: response codes

From Code to Product Lecture 7 — Web API Design — Slide 61 gidgreen.com/course

slide-62
SLIDE 62

Examples

From Code to Product Lecture 7 — Web API Design — Slide 62 gidgreen.com/course

slide-63
SLIDE 63

API explorer

From Code to Product Lecture 7 — Web API Design — Slide 63 gidgreen.com/course

slide-64
SLIDE 64

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

slide-65
SLIDE 65

Example apps

From Code to Product Lecture 7 — Web API Design — Slide 65 gidgreen.com/course

slide-66
SLIDE 66

Discussion forum

From Code to Product Lecture 7 — Web API Design — Slide 66 gidgreen.com/course

slide-67
SLIDE 67

Lecture 7

  • Introduction
  • REST
  • Data formats
  • Security
  • Maintenance
  • Documentation
  • Conclusion

From Code to Product Lecture 7 — Web API Design — Slide 67 gidgreen.com/course

slide-68
SLIDE 68

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

slide-69
SLIDE 69

Books

From Code to Product Lecture 7 — Web API Design — Slide 69 gidgreen.com/course

slide-70
SLIDE 70

Resources and services

From Code to Product Lecture 7 — Web API Design — Slide 70 gidgreen.com/course