[ianb]

> Arguing to replace a well-defined single idiom (verbs) with some arbitrary combination of URI, custom headers, request body contents is exactly the opposite of what you want.

It may not be what you want, but it is what you'll get. It's what you'll get now, and in the future. There isn't much in the way of discoverable APIs that adhere to the data model suggestion in the HTTP spec, and that's becoming more true as time goes on. As HTTP APIs become more popular they have become less normalized. It's natural: if you want to expose something, you want to expose it as it is. Not many things adhere to the verb structure of HTTP, I'm not sure anything does unless it was designed to be HTTP from the ground up – which isn't how you should design an API, you should design it to do something useful from the ground up.

[lusr]

> There isn't much in the way of discoverable APIs that adhere to the data model suggestion in the HTTP spec

I don't even understand why this needs to be pointed out. If the precise usage of all web APIs could be inferred from the verb alone, presumably all web APIs are exactly the same. That's nonsensical. I challenge anybody to honestly claim they have consumed a 3rd party web API of material complexity without once referring to the documentation and solely relying on guessing HTTP verbs.

Once you're already reading the API documentation, I don't understand why you'd prefer "http.request('PUT', '/resource')" over "http.post('/resource/put'). Even better, you can choose a URI that makes the most sense to your domain model, e.g. '/resource/upload'. I don't understand why you'd want to have less expressive URIs AND more work. In even this simple example, the verb is unlikely to be adequate in any case - if you need to supply options or metadata the verb is even less significant as to the true meaning of the operation.

The fact is you can always embed the verb of your choice into the URI - thereby making a GET/POST/HEAD world no more or less expressive than a Verbtopia world. All that extra verbs do is cause consumers of the API to have to remember two pieces of information (VERB + URI) rather than one (URI). At least URIs can be constructed to make as much semantic sense as possible within a given domain model - VERBs, on the other hand, end up as square pegs in round holes, making them far less memorable.

[dragonwriter]

Ideally, a REST API would only require consulting the documentation on media types and the location of the root endpoint, but the kind of media-type heavy, hyperlink driven driven specification that would support that is rare.

Though specifications aimed at improving at least the hypermedia part of that are starting to gain traction.

[lusr]

I still don't see the value. To me it's like proposing that in SQL we replace 'EXEC' with 'HEAD', 'PUT', 'DELETE'...

At the end of the day I still need to understand the contract of the stored procedure to have any hope of consuming a database API of meaningful complexity.

[dragonwriter]

> I still don't see the value.

The value is loose coupling and composability; each media-type is its own contract, and hypermedia provides a common mechanism for discovering the location of endpoints.

This allows different APIs (and their clients) to share common components rather than every large API being a special snowflake.

> To me it's like proposing that in SQL we replace 'EXEC' with 'HEAD', 'PUT', 'DELETE'...

A better SQL equivalent is proposing that you expose to each consumer an appropriate set of relations (likely views) as the application's interface to the database rather than stored procs (the data description of the view is the analog of the media type of the REST resource.)