[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.)