API Design


Idempotent
- Idempotent key
stateless


Rest(Http) API Design
Hackable, intuitive url
Service health check APIs
Caching
Time-based cache headers
Conditional cache headers
- ETag and If-Modified-Since, If-None-Match
- request.evaluatePreconditions(tag)
Add X-Request-ID to request
Versioning
- Accept: application/json; version=3

Rate limit
Security, Auth
Audit

Use plural noun
GET /api/dogs/{id}
GET /api/dogs/?name=xxx

Relationship
/{relationship-name}[/{resource-id}]/…/{relationship-name}[/{resource-id}]
GET /persons/1/dogs

Query
GET /persons;id=1/dogs GET /persons;name=blabla/dogs
GET /dogs?color=red&state=running&location=park

Partial Fields
/dogs?fields=name,color,location

Actions
/resources/:resource/actions/:action

"kind": "Dog"
"ownerID": "98765432",
"kind": "Collection",

hypermedia - HATEOAS
"ownerLink": "https://dogtracker.com/persons/98765432"
selfLink
"self": "https://dogtracker.com/dogs?limit=25,offset=0",
"kind": "Page",
"pageOf": "https://dogtracker.com/dogs",
"next": "https://dogtracker.com/dogs?limit=25,offset=25",

201 Created
301 Moved Permanently
304 Not Modified
401 Unauthorized
403 Forbidden

Resources
Heroku's HTTP API Design Guide

Labels

adsense (5) Algorithm (69) Algorithm Series (35) Android (7) ANT (6) bat (8) Big Data (7) Blogger (14) Bugs (6) Cache (5) Chrome (19) Code Example (29) Code Quality (7) Coding Skills (5) Database (7) Debug (16) Design (5) Dev Tips (63) Eclipse (32) Git (5) Google (33) Guava (7) How to (9) Http Client (8) IDE (7) Interview (88) J2EE (13) J2SE (49) Java (186) JavaScript (27) JSON (7) Learning code (9) Lesson Learned (6) Linux (26) Lucene-Solr (112) Mac (10) Maven (8) Network (9) Nutch2 (18) Performance (9) PowerShell (11) Problem Solving (11) Programmer Skills (6) regex (5) Scala (6) Security (9) Soft Skills (38) Spring (22) System Design (11) Testing (7) Text Mining (14) Tips (17) Tools (24) Troubleshooting (29) UIMA (9) Web Development (19) Windows (21) xml (5)