Hacker Newsnew | comments | show | ask | jobs | submit | kirang1989's comments login

The short history of nearly everything - Bill Bryson

This book rekindled my interest and love for science.

-----


A brilliant book indeed!

-----


Python/Flask

-----


Computer Systems: A Programmer's Perspective and NAND2Tetris: Elements of Computing Systems are the best books to learn the internals of computer hardware and solidify your understanding of how a computer works.

The Pragmatic Programmer - My all time favorite. Awesome book to learn best practices of various aspects in programming.

The Code Book: The Evolution Of Secrecy From Mary, Queen Of Scots To Quantum Cryptography, if you have a thing for cryptography.

-----


For starters, if you aren't quite used to the the workflow of contributing to an open source project, you could start helping out by submitting some good reads to pycrumbs (https://github.com/kirang89/pycrumbs).

-----


This is pretty cool for phone interviews, but I certainly do hope that people refrain from using this as their only method of interviewing candidates.

-----


Any good resources to read more about "discoverability" that you'd recommend ?

-----


The original thesis on REST by Roy Fielding is a good start, to understand the real motivation behind creating it.

Martin Fowler has a good article on the Richardson Maturity Model, and what each part means: http://martinfowler.com/articles/richardsonMaturityModel.htm...

Finally, for an example of why HATEOAS is a good thing, and why APIs should be at level 3 on the RMM, Jon Moore has a good talk on Hypermedia APIs here: http://vimeo.com/20781278

As far as I am aware, there are very few companies actually applying these principles. GitHub is doing something close to it in their API, and I have heard that Google uses this sort of system for their APIs extensively on internal projects. In terms of new-web-API-startup like companies, Twilio/Stripe et. al, I have yet to see many take it this far.

-----


I see. Thank you for the resources :)

-----


Precisely the reason why I enojoy integrating Stripe or Twilio. They've abstracted a complex service with a beautiful API and awesome documentation.

-----


Yes, those points are general traits of all great software. But there are still API's out there that fail to conform to those basic principles and that's why I wanted to write the post as a checklist to self, to remind as to what makes an API great.

-----


Yes, but the world is now reading ;)

I found this very simplistic, but then I didn't realize it was a checklist for yourself. A few notes, if I may:

first, it is generally recognized that it takes 3 or so tries to get an API/framework correct. Meaning used in 3 or so representative projects. Oh, if you are essentially copying another API in a different language or whatever than the hard work is done. But recognize there will be a lot of refactoring going on in greenfield development. So you probably don't want to do big design up front, as you will get it wrong. Accept that. I'm sure we can point out some genius counter-example, but for us mortals the rules apply.

You touch on some of that in the post, but for me it is always the biggest, most important thing, and it almost always get treated as the elephant in the room that no one really acknowledges, or kind of just hand waves away, and go off and invest 3 months of work into something that is broken and unusable even before public release.

Second, I'm not sure you captured another vital component - that of safety. One of the MS Press books (I forget which one) uses a vending machine analogy. There was a vending machine in the office that had you punch in 2 numbers to get a product. A digit for the row, another for the column. Perfectly usable, except there was endless cursing because inevitably people would punch in the #s in the wrong order, and get something they didn't want. The trivial fix is to use letters for columns, and #s for rows, so the KitKat bar is A3, and the gum is C1. Fixes are often a lot less trivial in code APIs. But you need to design them so the user cannot easily shoot themselves in the foot. How many hours have you struggled with a 3rd party library because it looks like you connected everything up correctly, but nothing works? The API allows you to do things that have no meaning.

-----


Consistency indeed ! Thanks :)

-----

More

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact

Search: