This would be a good related subthread: links to API docs for what people consider to be both great, and terrible, APIs.
At least the great part has happened:
https://news.ycombinator.com/item?id=867972
There was one _much_ more recently (a week or two ago), but funnily enough the only one I can find is ~2.5k days old..
Related - best documented:
[1] https://news.ycombinator.com/item?id=868102
[2] http://web.archive.org/web/20090520234149/http://chaos.troll...
People get into really philosophical discussions around versioning, resource structure, etc... but in reality think about what makes you like the APIs you like over another alternative. Then think about what you would do to make it even easier to use/integrate with.
There also with some APIs is the tradeoff of easy integration and long-term flexibility.. things like that.
Don't be overwhelmed by this though -- API design isn't an exact science. It's also very opinionated.
Personally, I would just start reading actual API documentation (GitHub is a great place to start -- their API is a joy to work with). Find things you like and don't like about it and try to figure out why those decisions were made.