├── .gitignore └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | 5 | # Runtime data 6 | pids 7 | *.pid 8 | *.seed 9 | 10 | # Directory for instrumented libs generated by jscoverage/JSCover 11 | lib-cov 12 | 13 | # Coverage directory used by tools like istanbul 14 | coverage 15 | 16 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 17 | .grunt 18 | 19 | # Compiled binary addons (http://nodejs.org/api/addons.html) 20 | build/Release 21 | 22 | # Dependency directory 23 | # Commenting this out is preferred by some people, see 24 | # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git- 25 | node_modules 26 | 27 | # Users Environment Variables 28 | .lock-wscript 29 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # GOTO: https://github.com/dwyl/learn-api-design (_latest version_) 2 | 3 | Essential learning for people building an API 4 | 5 | ![Grandma Remote](http://i.imgur.com/pdrRPjm.jpg) 6 | 7 | Joking aside, ***starting*** a project "***from scratch***" is a ***opportunity*** 8 | (and *privilege*) ***few people get***. 9 | If you are ***fortunate*** enough to be 10 | in that position, ***do not take*** the **task** ***lightly***. 11 | 12 | ![golden ticket](http://i.imgur.com/U6a5SCh.jpg) 13 | 14 | Building the *interface* for a new project is nothing short of a ***Golden Ticket***! So do your homework *before* you start! 15 | 16 | ## Intro 17 | 18 | Having a *great* API will make or break your project/product. 19 | 20 | A few ***quotes*** from 21 | [**Joshua Bloch**](http://en.wikipedia.org/wiki/Joshua_Bloch)'s 22 | Google Talk on 23 | ["***How To Design A Good API and Why it Matters***"](http://youtu.be/heh4OeB9A-c) 24 | and [Kevin Lacker](https://twitter.com/lacker)'s ([@Parse](https://parse.com/products)) 25 | ["***How to Design Great APIs***"](https://www.youtube.com/watch?v=qCdpTji8nxo) 26 | > - - - 27 | > "*You have* ***one chance*** *to* ***get it right***." 28 | [3:17](http://youtu.be/heh4OeB9A-c?t=3m17s) 29 | - - - 30 | > "***A bad API*** *can be amoung a company's greatest liabilities... 31 | > can cause an un-ending stream of support phonecalls ... 32 | and it **can inhibit** a company's **ability to move forward***" 33 | [2:51](http://youtu.be/heh4OeB9A-c?t=2m51s) 34 | - - - 35 | > "*Once you have a* ***bad API***, *you* ***can't change it***, 36 | *you are pretty much* ***stuck with it forever***." [3:12](http://youtu.be/heh4OeB9A-c?t=2m51s) 37 | - - - 38 | > " ... ***A good API*** *needs to* ***appeal to*** *the most powerful emotion*: ***Laziness***". 39 | [3:23](http://youtu.be/qCdpTji8nxo?t=3m23s) 40 | - - - 41 | > "*You need to* ***be opinionated*** *even when* ***there is no right and wrong***" 42 | [31:02](http://youtu.be/qCdpTji8nxo?t=31m2s) 43 | - - - 44 | > "*Always make your REST API* ***as small/short as possible***" 45 | [31:19](http://youtu.be/hdSrT4yjS1g?t=31m19s) 46 | - - - 47 | 48 | ## Characteristics of a Good API 49 | 50 | + ***Easy to learn*** (*notice the priority placement of learn-ability...*) 51 | + Intuitive / Easy to ***use*** even without documentation 52 | + ***Hard to misuse*** (*write tests for "undesireable" behaviour*) 53 | + Easy to *read* and *maintain* code that uses it 54 | + Sufficiently powerful to satisfy requirements 55 | + Easy to ***evolve*** (*the simpler the initial API the easier it will be to extend*) 56 | + Appropriate to ***audience*** (*make it beginner friendly*...) 57 | + ***Opinionated*** (means people don't have to *think*) 58 | 59 | 60 | ## Types of API 61 | 62 | ### REST 63 | 64 | **Representational State Transfer** (**REST**) is a software architecture 65 | style consisting of guidelines and best practices for creating 66 | scalable web services. 67 | 68 | 69 | ### What is a RESTful web service? 70 | 71 | ![restful API](http://i.imgur.com/xKXnKGT.jpg) 72 | 73 | [ReST](http://en.wikipedia.org/wiki/Representational_state_transfer) 74 | is a structured way of building web services and applications. 75 | When something is described as "RESTful" it simply means it follows a 76 | predefined predictable pattern for how it responds to requests. 77 | 78 | #### Video Explanation of REST 79 | 80 | - Intro to REST: http://youtu.be/llpr5924N7E 81 | - Google Developers Intro to REST: https://www.youtube.com/watch?v=YCcAE2SCQ6k 82 | 83 | #### Read more about REST APIs / RESTful Web Services 84 | 85 | - REST Wikipedia: http://en.wikipedia.org/wiki/REST (*Skim* and make sure you understand the concepts) 86 | - Beginners Guide: http://www.restapitutorial.com/ 87 | - Basic Q&A for REST: http://katgleason.tumblr.com/post/37836552900/how-i-explained-rest-to-my-wife 88 | - What are RESTful web services: http://stackoverflow.com/a/3636470/1148249 89 | - What is "CRUD"? http://en.wikipedia.org/wiki/Create,_read,_update_and_delete 90 | 91 | 92 | #### Why REST? 93 | 94 | + Scalability (dissemination - more people use your API) 95 | + Generality 96 | + Independence 97 | + Latency (Caching) 98 | + Security 99 | + Encapsulation 100 | 101 | #### Verbs 102 | 103 | + **GET** = **read** an existing **record** or collection (list of records) 104 | + **POST** = **create** and ***partial*** update. 105 | + **PUT** = **create** and [***indepotent***](http://stackoverflow.com/a/1077489/1148249) update 106 | (always send **all** the fields required - not partial update) 107 | + **DELETE** = does exactly what it says 108 | 109 | ##### Examples 110 | 111 | + **GET** /comment - Returns a list of all comments 112 | + **GET** /comment/:id - Returns a comment with the given id 113 | + **POST** /comment - Creates a new comment 114 | + **PUT** /comment/:id - Updates a comment with the given id 115 | + **DELETE** /comment/:id - Deletes a comment with the given id 116 | 117 | #### Tips 118 | 119 | To reduce the amount of data retrieved, 120 | we can *specify* the exact fields we want in url e.g: 121 | ``` 122 | GET /accounts/1234/fields=firstname,surname,etc 123 | ``` 124 | see: [52:29](http://youtu.be/hdSrT4yjS1g?t=52m29s) 125 | 126 | #### Reading / Watching 127 | 128 | + **What** is **REST**? 129 | (if you haven't already read it, read the REST Wikipedia article): 130 | http://en.wikipedia.org/wiki/Representational_state_transfer 131 | + The 5 Things Every API Must Have: 132 | https://blog.newrelic.com/2014/09/08/apipunchlist/ 133 | + Best Practices for Designing a Pragmatic RESTful API (***Great*** article) 134 | http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api 135 | + REST+JSON API Design - Best Practices for Developers 136 | http://youtu.be/hdSrT4yjS1g (*comprehensive* overview) 137 | + Secure Your API - Tips for REST + JSON Developers 138 | http://youtu.be/FeSdFhsKGG0 139 | + PUT vs POST in REST: 140 | http://stackoverflow.com/questions/630453/put-vs-post-in-rest 141 | 142 | #### Examples of Successful (Good) APIs 143 | 144 | + Parse REST API: https://www.parse.com/docs/rest 145 | (really good example of good interactive documentation) 146 | + GitHub: https://developer.github.com/ 147 | + Twitter: https://dev.twitter.com/rest/public 148 | + Google: https://developers.google.com/custom-search/json-api/v1/using_rest 149 | + Stripe: https://stripe.com/docs/api 150 | 151 | #### Useful Resources 152 | 153 | + **lout** API documentation generator (for hapi.js apps): 154 | https://github.com/hapijs/lout 155 | + RESTful web API Documentation Generator. 156 | http://apidocjs.com 157 | + Swagger - The World's Most Popular Framework for APIs: 158 | http://swagger.io 159 | 160 | ### Streaming 161 | 162 | ### WebSockets 163 | 164 | #### Reading 165 | 166 | + **Q**: Can we use WebSockets? http://caniuse.com/#feat=websockets 167 | **Answer**: ***YES***! IE 10+, Safari/iOS Safari 7.1+, Android 4.4+ & Android Chrome 168 | + About WebSockets: https://www.websocket.org/aboutwebsocket.html 169 | + WebSocket MDN: https://developer.mozilla.org/en/docs/WebSockets 170 | + W3C WebSocket API: http://www.w3.org/TR/2011/WD-websockets-20110419/ 171 | + CloudFlare WebSockets (good intro): https://blog.cloudflare.com/cloudflare-now-supports-websockets/ 172 | + SitePoint article on WebSockets in HTML5: 173 | http://www.sitepoint.com/introduction-to-the-html5-websockets-api/ 174 | + Socket.io Chat Example (uses express): http://socket.io/get-started/chat/ 175 | + Socket.io Max Connections? 250k: 176 | http://stackoverflow.com/questions/10161796/how-many-users-nodejs-socket-io-can-support 177 | 178 | #### Examples 179 | 180 | + Twitter Streaming API: 181 | https://dev.twitter.com/streaming/overview 182 | + Salesforce Streaming API: 183 | http://www.salesforce.com/developer/docs/api_streaming/ 184 | 185 | 186 | ## Versioning your API? 187 | 188 | ![API Versioning](http://i.imgur.com/lu5DhRy.jpg) 189 | 190 | There is on-going debate on whether APIs should be versioned 191 | and if so, how should this be done. 192 | 193 | There are two primary approaches to versioning [32:43](http://youtu.be/hdSrT4yjS1g?t=32m43s) 194 | 195 | ### Intro Reading 196 | 197 | + Your API versioning is wrong: 198 | http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html 199 | + The debate on API versioning: 200 | http://stackoverflow.com/questions/389169/best-practices-for-api-versioning 201 | + Issues with API version in the URL/URI: 202 | https://www.mnot.net/blog/2012/12/04/api-evolution 203 | + Evolving HTTP APIs 204 | https://www.mnot.net/blog/2012/12/04/api-evolution 205 | 206 | ### Wrong way 1 – URL versioning 207 | 208 | ```sh 209 | HTTP GET: 210 | https://haveibeenpwned.com/api/v2/breachedaccount/foo 211 | ``` 212 | 213 | ### Wrong way 2 - custom request header 214 | 215 | ```sh 216 | HTTP GET: 217 | https://haveibeenpwned.com/api/breachedaccount/foo 218 | api-version: 2 219 | ``` 220 | 221 | ### Wrong way 3 - content type: 222 | 223 | ```sh 224 | HTTP GET: 225 | https://haveibeenpwned.com/api/breachedaccount/foo 226 | Accept: application/vnd.haveibeenpwned.v2+json 227 | ``` 228 | ### Further Reading (Versioning) 229 | 230 | + Pivotal Labs API Versioning guide: http://pivotallabs.com/api-versioning/ 231 | + SemVer: http://semver.org/ 232 | + Stripe's API Versioning: https://stripe.com/docs/api#versioning 233 | + *Comprehensive* List of how others are doing versioning: 234 | http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/ 235 | 236 | ## Caching 237 | 238 | + Caching API Requests: 239 | http://robots.thoughtbot.com/caching-api-requests 240 | + Caching your REST API 241 | http://restcookbook.com/Basics/caching/ 242 | + API Caching 243 | http://www.fastly.com/blog/api-caching-part-1/ 244 | + Caching and rate limiting: 245 | https://blog.apigee.com/detail/api_scalability_part_2_-_caching_rate_limits_and_offloading 246 | + Thoughtbot caching insights (mostly ruby-focussed): 247 | http://robots.thoughtbot.com/caching-api-requests 248 | 249 | 250 | ## General Background Reading + Watching 251 | 252 | + What is an API? (very basic intro): http://youtu.be/B9vPoCOP7oY 253 | + **BASIC** Introduction to APIs by [Derek Dahmer](https://github.com/ddgromit) 254 | @ General Assembly: 255 | https://www.youtube.com/watch?v=FknvOGcLHmc (Google for Entrepreneurs - *absolute beginner*?) 256 | + Wikipedia: http://en.wikipedia.org/wiki/Application_programming_interface 257 | + The REST Cookbook: http://restcookbook.com (comprehensive guide) 258 | + How to Design Great APIs - Parse: 259 | https://www.youtube.com/watch?v=qCdpTji8nxo 260 | + How To Design A Good API and ***Why it Matters***: 261 | http://youtu.be/heh4OeB9A-c + http://lcsd05.cs.tamu.edu/slides/keynote.pdf 262 | (mostly related to the Java Language API but a few general insights) 263 | + Best practices (mostly relating to library APIs not REST/Stream): 264 | http://stackoverflow.com/questions/2619854/best-practices-and-guidelines-for-designing-an-api 265 | + Parse ***interactive*** API reference: 266 | http://youtu.be/qCdpTji8nxo?t=21m15s 267 | + Principals of good RESTful API design: 268 | http://codeplanet.io/principles-good-restful-api-design/ 269 | + Building Hypermedia APIs with HTML5 and Node: 270 | http://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578 271 | + Designing APIs for Asynchrony: 272 | http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony 273 | + API Design Principles: http://qt-project.org/wiki/API-Design-Principles 274 | (general principals. ignore the QT-specific parts) 275 | --------------------------------------------------------------------------------