REST (Representational state transfer) is arguably the most popular architectural style for designing HTTP-based web APIs these days. While the basic idea is easy to understand, there’s a lot of corner cases that are not so straightforward. This has been on my mind lately while trying to revise the conventions for VocaDB’s REST API. It turns out that finding answers to some of these questions is difficult, and finding concrete examples of “proper” REST APIs that follow the conventions as precisely as possible is even more difficult. I decided to write something about the issues I’ve faced.