Generalize the URL recommendations

[konklone]

Right now, the URL recommendations are pretty specific and strict:

* A URL identifies a resource.
* URLs should include nouns, not verbs.
* Use plural nouns only for consistency (no singular nouns).
* Use HTTP verbs (GET, POST, PUT, DELETE) to operate on the collections and elements.
* You shouldn’t need to go deeper than resource/identifier/resource.
* Put the version number at the base of your URL, for example http://example.com/v1/path/to/resource.
* URL v. header:
    * If it changes the logic you write to handle the response, put it in the URL.
    * If it doesn’t change the logic for each response, like OAuth info, put it in the header.
* Specify optional fields in a comma separated list.
* Formats should be in the form of api/v2/resource/{id}.json

### Good URL examples
* List of magazines:
    * GET http://example.gov/api/v1/magazines.json
* Filtering is a query:
    * GET http://example.gov/api/v1/magazines.json?year=2011&sort=desc
    * GET http://example.gov/api/v1/magazines.json?topic=economy&year=2011
...

It's not that these are bad suggestions -- but there are lots of times when it's not necessary to exert this level of Fielding-ian rigor.

And every API is different! API URLs can and should adapt to make the simplest possible (and no simpler) interface for their function.

So I'd generalize this to a smaller set of core principles, in rough order of importance:

1. Avoid single-endpoint APIs. Don't jam multiple operations into the same endpoint with the same HTTP verb.
2. Prioritize simplicity. It should be easy to guess what an endpoint does by looking at the URL and HTTP verb, without needing to see a query string.
3. Generally speaking, your API's URLs should advertise resources, and avoid verbs.