API.js

Bootstrapping an API in node.js with express.js and Redis. Testing with Mocha and Documentation in iodocs and Dox.

Transcript

1. A P I Patrick Heneise
2. With ♡ from BarcelonaJS.
3. Apis, Egyptian god of strength and fertility
7. http://icity-devp.icityproject.com
9. Let’s talk about your API
10. What makes a good API? ★ Performance ★ Scalability ★ Reusability ★ Evolvability ★ Documentation ★ Testability ★ Value ★ Easy to learn & use ★ Hard to misuse
11. ‘Once you have a bad API, you can not change it. Forever. You’ve got one chance how to make it right.’ – Joshua Bloch, Google Tech Talk, Jan 2007
12. Why node.js is the right tool! ★ Double-click to edit.
13. It’s not.
14. Choose your weapons carefully!
15. But node.js has some nice features. And it’s cool. Because it’s JavaScript. And JavaScript is cool, right?
16. So let’s create an API in node.js
19. The Demo API
20. The Cat API!
22. Seriously?
23. So, introducing: The Junk API https://github.com/ PatrickHeneise/TheJunkAPI
24. ‘An API should do one thing, and to it well.’ Joshua Bloch, Google Tech Talk, Jan 2007
25. Adding, listing, showing and deleting: Junk.
26. app.get('/api/junks', junk.index); app.get('/api/junk/:id', junk.show); app.post('/api/junk', junk.create); app.delete('/api/junk/:id', junk.remove);
27. exports.show = function(req, res) { var id = req.params.id; redis.hgetall('junk:' + id, function (error, junk) { if (junk === null) { res.send(404); } else { res.send(200, junk); } }); };
28. Input / Output
29. ★ params: /api/junk/1 ★ query: /api/junk?id=1 ★ body: /api/junk -d {‘id’: 1} ★ Choose your weapon carefully! Input
30. ★ HTTP Status Codes ★ Response Body ★ Use the standards! Output
34. ★ 200 - Success ★ 201 - Created ★ 204 - No content ★ 401 - Unauthorized ★ 403 - Forbidden ★ 404 - Not Found ★ 409 - Conflict ★ 500 - Internal Server Error HTTP Status Codes
35. res.send(200, {});
36. Authentication
37. passport.js
38. ★ OAuth ★ OAuth2 ★ api key ★ HTTP Basic ★ HTTP Digest ★ ...
39. Again, choose your weapon carefully!
40. Testing
41. ★ mocha http://visionmedia.github.io/ mocha/ ★ vows http://vowsjs.org ★ specify https://github.com/dscape/ specify
42. mocha
43. describe('GET /junk/:id', function () { it('should return details of the junk', function (done) { request(url) .get('/junk/0') .set('apikey', 'asdasjsdgfjkjhg') .send() .end(function (error, response) { response.status.should.equal(200); response.body.text.should.equal('iz likin myself on lolcats.com'); should.exist(response.body.url); done(error); }); });
44. Prepare your testing environment!
45. ‘And clean up afterwards!’ - Mum
46. before(function (done) { ! require('./before').before(function () { ! ! done(); ! }) }); after(function (done) { ! require('./after').after(ids, function() { ! ! done(); ! }); });
47. Junk GET /junks ✓ should return a list of junk GET /junk/:id ✓ should return details of the junk ✓ should fail with 404 POST /junk ✓ should create new junk ✓ should fail to create new junk DELETE /junk/:id ✓ should delete junk, huzzah! ✓ should fail to delete junk 7 passing (1s)
48. Yay. ✓
49. Documentation
51. ★ http://jsdox.org ★ https://github.com/visionmedia/ dox - JavaScript documentation generator ★ https://github.com/mashery/ iodocs - I/O Docs - Open Source in Node.js
52. Dox
53. /** * Output a single piece of junk specified by :id * * @param {Number} id * @return {Object} All junk details * @api public */
55. iodocs
57. Resources
58. (no more cats)
59. ★ How To Design A Good API and Why it Matters http://www.youtube.com/watch?v=aAb7hSCtvGw http://lcsd05.cs.tamu.edu/ slides/keynote.pdf ★ http://stackoverflow.com/ questions/2619854/best-practices- and-guidelines-for-designing-an- api ★ https://dev.twitter.com//
60. Thank you. Patrick Heneise @Patrick Heneise http://patrickheneise.com