The document discusses best practices and guidelines for designing APIs, including performance, scalability, reusability, documentation, testing, and more. It then demonstrates creating a sample "Junk API" in Node.js, showing how to add, list, show, and delete junk data using routes, Redis, and testing with Mocha. Documentation for the API is also generated using JSDoc.

1. A
P
I
Patrick
Heneise

2. Apis,Egyptiangodofstrengthandfertility

6. http://icity-devp.icityproject.com

8. Let’stalkabout
yourAPI

9. WhatmakesagoodAPI?
★ Performance
★ Scalability
★ Reusability
★ Evolvability
★ Documentation
★ Testability
★ Value
★ Easytolearn&use
★ Hardtomisuse

10. ‘OnceyouhaveabadAPI,youcannotchange
it.Forever.You’vegotonechancehowto
makeitright.’–JoshuaBloch,GoogleTechTalk,Jan2007

11. Whynode.jsisthe
righttool!
★ Double-clicktoedit.

12. It’snot.

13. Chooseyour
weaponscarefully!

14. Butnode.jshassome
nicefeatures.
Andit’scool.
Becauseit’sJavaScript.
AndJavaScriptiscool,
right?

15. Solet’screatean
APIinnode.js

18. TheDemoAPI

19. TheCatAPI!

21. Seriously?

22. So,introducing:
TheJunkAPI
https://github.com/
PatrickHeneise/TheJunkAPI

23. ‘AnAPIshoulddoonething,andtoitwell.’
JoshuaBloch,GoogleTechTalk,Jan2007

24. Adding,listing,
showinganddeleting:
Junk.

25. 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);

26. exports.show=function(req,res){
varid=req.params.id;
redis.hgetall('junk:'+id,function(error,junk){
if(junk===null){
res.send(404);
}else{
res.send(200,junk);
}
});
};

27. Input/Output

28. ★ params:/api/junk/1
★ query:/api/junk?id=1
★ body:/api/junk-d{‘id’:1}
★ Chooseyourweaponcarefully!
Input

29. ★ HTTPStatusCodes
★ ResponseBody
★ Usethestandards!
Output

33. ★ 200-Success
★ 201-Created
★ 204-Nocontent
★ 401-Unauthorized
★ 403-Forbidden
★ 404-NotFound
★ 409-Conflict
★ 500-InternalServer
Error
HTTPStatusCodes

34. res.send(200,{});

35. Authentication

36. passport.js

37. ★ OAuth
★ OAuth2
★ apikey
★ HTTPBasic
★ HTTPDigest
★ ...

38. Again,chooseyour
weaponcarefully!

39. Testing

40. ★ mocha
http://visionmedia.github.io/
mocha/
★ vows
http://vowsjs.org
★ specify
https://github.com/dscape/
specify

41. mocha

42. 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);
});
});

43. Prepareyour
testing
environment!

44. ‘Andcleanupafterwards!’-Mum

45. before(function(done){
! require('./before').before(function(){
! ! done();
! })
});
after(function(done){
! require('./after').after(ids,function(){
! ! done();
! });
});

46. 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)

47. Yay.✓

48. Documentation

50. ★ http://jsdox.org
★ https://github.com/visionmedia/
dox-JavaScriptdocumentation
generator
★ https://github.com/mashery/
iodocs-I/ODocs-OpenSourcein
Node.js

51. Dox

52. /**
*Outputasinglepieceofjunk
specifiedby:id
*
*@param{Number}id
*@return{Object}Alljunkdetails
*@apipublic
*/

54. iodocs

56. Resources

57. (nomorecats)

58. ★ HowToDesignAGoodAPIandWhy
itMattershttp://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//

59. Thankyou.
PatrickHeneise
@PatrickHeneise
http://patrickheneise.com