Some thinking points for service design: Principles & Best practices of REST API Design.
Today I discovered: Documenting APIs: A guide for technical writers and engineers.
Some tools for API documentation: Say Goodbye to Manual Documentation with these 6 tools.
Today I stumbled upon Microsoft REST API Guidelines.
I just wanted to get something that I’ve thought for many years on record, because I don’t think I’ve ever had the chance to discuss it much before, but I believe JSON web services (“REST APIs”) and web applications should deal only in two HTTP verbs, being: GET and POST. You use GET for queries and you use POST for submissions. All POST operations go through business logic for particular services and CRUDing URLs is a supremely bad idea, in my opinion. Just wanted to get that on record. Thanks. p.s for web applications you should 3xx on success, not 2xx on success; what you do for JSON web services is up to you, but for those 2xx is probably fine.
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
A fun read: Falsehoods Programmers Believe about REST APIs.