1. Pragmatic REST principles
1.1. URIs
1.1.1. Well designed URI makes it easy to discover, consume, and extend
1.1.2. Collections of objects should consist of a plural noun
1.1.2.1. /customers
1.1.3. Single objects consist of a plural noun followed by id
1.1.3.1. /customers/Bob
1.1.3.2. /accounts/123456
1.1.4. OK to start URI with identifying path. e.g. version mumber
1.1.4.1. /1
1.1.5. After the identifying path, only collections and objects
1.1.5.1. /1/accounts/123456
1.1.6. Standard set of query parameters
1.1.6.1. count - to determine how many objects to return
1.1.6.2. start - to determine where to count from
1.1.6.3. q -for generic freeform search over collections
1.1.7. Methods
1.1.7.1. Singular objects
1.1.7.1.1. GET to read
1.1.7.1.2. PUT for update
1.1.7.1.3. DELETE for delete
1.1.7.2. Collections
1.1.7.2.1. GET to read whole or part of collection
1.1.7.2.2. POST to add new object to collection
1.2. Parameters
1.2.1. Use standard and easy to guess optional parameters
1.3. Return codes
1.3.1. Leverage HTML standards
1.3.1.1. e.g. 404 when path does not resolve to a real object
1.4. Hide everything else
1.4.1. Security, Rate Limiting, Routing
1.4.2. Use headers
1.5. Establish clear conventions for versioning
1.6. Examples
1.6.1. Insert new item into the cart POST http:// api.shopping.com/ cart/ cartName
1.6.2. Delete item from the cart DELETE http:// api.shopping.com/ cart/ cartName/ item/ itemName
1.6.3. List everything in the cart GET http:// api.shopping.com/ cart/ cartName
1.6.4. Get an item in the cart GET http:// api.shopping.com/ cart/ cartName/ item/ itemName
1.6.5. Replace an entire item PUT http:// api.shopping.com/ cart/ cartName/ item/ itemName
1.6.6. Delete the whole cart DELETE http:// api.shopping.com/ cart/ cartName
1.6.7. Look at items 20 through 29 in cart GET http:// api.shopping.com/ cart/ cartName? start = 20& count = 10.
2. Design Principles
2.1. Design for the audience
2.1.1. Direct - Developers
2.1.1.1. Technology
2.1.1.1.1. Structure - Pragmatic REST
2.1.1.1.2. Data Format - JSON
2.1.1.1.3. Security - OAuth
2.1.2. Indirect - End Users
2.1.2.1. Understand what end users want
2.2. Differentiate your API
2.2.1. Data is unique, complete, accurate
2.2.2. Better support or easier signup process
2.2.3. More reliable, faster
2.2.4. More developer friendly terms - e.g. relaxed rate limits
2.3. Make API easy to try and use
2.3.1. Some level of free access
2.3.2. Instant gratification
2.3.2.1. Console that provides immediate testing
2.3.2.2. Some APIs do not require signup or authentication
2.3.3. Easy Signup
2.3.3.1. Only few questions
2.4. Make API easy to understand
2.4.1. Don't publish function that are irrelevant
2.4.2. Bundle with code samples
2.4.3. REST lends itself to simpler APIs
2.5. Don't do anything weird
2.5.1. Stick to conventions
2.5.2. Avoid complex or custom security schemes
2.6. Versioning
2.6.1. Include "1" in the version path
2.6.2. Every time you change API try hard to avoid incrementing to "2"
2.6.2.1. Work hard to avoid breaking the contract of the API
2.6.3. Key questions
2.6.3.1. What happens to older versions
2.6.3.2. What happens to apps delivered on older versions
2.6.3.3. Do new versions support all functionality of old apps
2.6.3.4. How many "one-off" versions for special partners
2.6.4. Mediation to support versioning
2.6.4.1. Transformations of API
2.6.4.1.1. Protocol
2.6.4.1.2. Data
2.6.4.1.3. Versions
2.6.4.1.4. Credentials
2.7. Scaling
2.7.1. Memcache - Reduce traffic to database server
2.7.2. Mediation (Proxy) - cache entire API responses
2.7.3. CDN - for large files that don't change
3. Security and User Management
3.1. Identification
3.1.1. Who is making the API request ?
3.1.2. API Keys
3.1.2.1. Simple to hand out
3.1.2.1.1. Often not encrypted or signed
3.1.2.2. Mostly an audit tool
3.1.2.3. Can be used to filter and block rogue applications
3.1.2.3.1. DDOS
3.1.2.3.2. Breaching terms of use
3.2. Authentication
3.2.1. Are they really who they say are ?
3.2.2. HTTP Basic
3.2.2.1. Simple, Universal
3.2.2.2. Relies on SSL for security
3.2.3. OAuth
3.2.3.1. Avoids reliance on passwords
3.2.3.1.1. OAuth Token - grants access to one application to one API on behalf of one user
3.2.3.1.2. Password - grants every application access to everything the password can unlock
3.2.3.1.3. Users can change passwords without breaking the apps
3.2.3.2. Various options
3.2.3.2.1. Bearer Token
3.2.3.2.2. Signature Option
3.2.4. Session Based Authentication
3.2.4.1. Login with username / password
3.2.4.2. Returns a session key - used for subsequent calls
3.2.5. Cookie Based Authentication
3.2.5.1. Used if you have control over client implementations
3.2.5.2. Grab cookie at session start to authenticate
3.2.6. Other
3.2.6.1. SAML
3.2.7. Use SSL Encryption always
3.2.7.1. Proliferation of Wifi, Mobile etc
3.3. Authorization
3.3.1. Are they allowed to do what they are trying to do ?
3.3.2. Data Masking
3.3.2.1. Obfuscating data that client does not have access to
3.3.2.2. Common layer to perform such transformations
3.3.2.2.1. Allows having a single API that supports all client tpes
3.4. Threat Detection and Prevention
3.4.1. Data Attacks
3.4.1.1. Large inputs
3.4.1.2. Large documents, attachments
3.4.1.3. Header Bombs
3.4.1.4. Replay attacks
3.4.1.5. Message Tampering
3.4.2. SQL injection attacks
3.4.3. XML injection attacks
3.4.4. API Gateways can be used to filter traffic
4. Operations and Management
4.1. Operational Info on Demand
4.1.1. API Status Page
4.1.1.1. e.g. Twitter
4.2. Traffic Management
4.2.1. Quotas
4.2.1.1. Limit number of calls made during a certain period of time
4.2.1.1.1. Hour, Day, Week ..
4.2.1.1.2. Pick the right granularity to protect the system
4.2.1.2. Assignee
4.2.1.2.1. User
4.2.1.2.2. Application
4.2.1.3. Infrastructure
4.2.1.3.1. Ability to increase quota
4.2.1.3.2. Ability to reset quota
4.2.2. Throttling
4.2.2.1. APIs are not rejected but slowed down
4.2.2.2. Implemented by an API gateway
4.2.2.2.1. Store the API calls
4.2.3. Spike Arresting
4.2.3.1. Shutdown hyperactive clients
4.2.3.2. Prevent DDOS, inefficient clients etc.
4.3. API Documentation
4.3.1. Intuitive API
4.3.2. Type of Docs
4.3.2.1. Reference Documentation
4.3.2.1.1. Every - API, Parameter,Return Value
4.3.2.2. Quick Start Guide
4.3.2.2.1. Good examples
4.3.2.2.2. API Console
4.3.2.3. Troubleshooting
4.3.2.3.1. API Status
4.3.2.3.2. Diagnosing error codes
4.3.2.4. Operations Runbook
4.3.2.4.1. For internal consumption
4.3.2.4.2. Responses to common problems
5. API Gateways
5.1. Support Security Schemes
5.1.1. OAuth, HTTP Basic, ...
5.2. Implement Traffic Management Policies
5.3. Cache frequent API results
5.3.1. New node
5.4. Transform API Requests and Responses
5.4.1. REST <-> SOAP
5.5. Data transformations and URI Rewrites
5.5.1. Support older versions of APIs
6. Value Chain
6.1. Provider of API
6.1.1. Does the provider own business assets ?
6.2. Target Audience
6.2.1. What is the size of the audience ?
6.2.2. Are there different segments in the audience ?
6.2.3. How does the audience benefit ?
6.3. Business Assets provided
6.3.1. Who should have access to each asset
6.4. Types of applications supported
6.4.1. What benefits from the application
6.4.2. How will applications be discovered
6.5. Users of apps created
6.5.1. What benefits do they get
7. Business Models
7.1. Free
7.2. Developer Pays
7.2.1. Tiered
7.2.2. Usage Based (Pay as you Go)
7.2.3. Consumption of resource
7.2.3.1. Storage, Compute Units etc.
7.2.4. Freemium
7.3. Developer Gets Paid
7.3.1. Revenue Share
7.3.2. Affiliate
7.3.2.1. Cost per Click
7.3.2.2. Cost per Action
7.3.3. Referral
7.3.3.1. One Time Fee
7.3.3.2. Recurring share of revenue
7.4. Indirect
7.4.1. Increasing Awareness
7.4.2. Drive Sales of other products
8. Other
8.1. API Team
8.1.1. Developer Evangelist
8.1.1.1. Sells the idea to internal and external stakeholders
8.1.1.2. Engages with developers
8.1.1.3. Technical + Marketing skills
8.1.2. Product Manager
8.1.2.1. Drives the roadmap
8.1.2.2. Understands how the API is performing
8.1.2.3. Designs the API
8.1.3. Engineers
8.1.3.1. Design the API
8.1.3.2. Write the API
8.1.4. Quality Assurance
8.1.5. Marketing
8.1.5.1. Branding guidelines
8.1.6. Legal
8.1.6.1. Defines usage of corporate and customer data
8.1.6.2. Vets content licensed from third parties
8.2. Objections to APIs
8.2.1. Afraid content may be misused
8.2.1.1. Less risky than content on a web site
8.2.1.2. Can identify and shut down abusive users
8.2.2. Afraid of load on systems
8.2.2.1. Rate Limiting can be used
8.2.2.2. Increased load is good
8.2.3. Afraid of security threats
8.2.3.1. Measures used to protect websites must be used
8.2.4. Afraid of exposing business assets
8.2.4.1. Use rights management