How To Design A Good API and Why it Matters

Today I watched: How To Design A Good API and Why it Matters. Good talk. Favourite quote:

Inheritance violates encapsulation

Oh, and I followed on with: A Brief, Opinionated History of the API wherein (t=28:14) Bloch says it’s an API if you can answer yes to both of these:

  1. Does it provide a set of operations defined by their inputs and outputs?
  2. Does it admit reimplementation without compromising its users?

Best practices for REST API design

Over on the StackOverflow blog: Best practices for REST API design. Some of it is good but I disagree with a bunch of things. I made some notes:

* Use singular

https://www.example.com/comment/list

Not:

https://www.example.com/comments


* Use multidimensional selectors, not path/hierarchical selectors:

https://www.example.com/comment/list?artist=nirvana&album=nevermind

Not:

https://www.example.com/album/nirvana/nevermind/comments


* Use noun/verb format:

https://www.example.com/comment/list
https://www.example.com/comment/register
https://www.example.com/comment/edit/54688
https://www.example.com/comment/view/54688
https://www.example.com/comment/reply/54688


* The [ noun, verb ] pairs map to Facilities for implementation:

[ comment, list ] => CommentLister
[ comment, edit ] => CommentEditor
[ comment, view ] => CommentViewer

Facilities have submit/render functionality and round-trip view state.


* HTTP success 30x's not 2xx's.


* Include a 'submission ID' on <form> elements for idempotent operations


* GET and POST only, don't CRUD URLs, rather invoke business processes