There are two aspects to discoverability: A) listing all of the operations, and B) getting detailed method signatures for a particular operation.
A) is a noble idea but so far few people need to automatically discover and consume web services. B is the real issue: something like SOAP was necessary to make RPC possible over the web for typed languages like C# and Java.
REST was a counterargument made by some people coming from a dynamic languages standpoint who really didn't need as much information as the statically typed language people. Its too bad that people have taken A so seriously though and gotten confused or misled (probably deliberately) about what SOAP was for and then tried to make REST into that.
The most convenient and useful API, even over the web, is one that is as close to normal programming as possible. In other words, RPC-style (or some improvement on that like NowJS). That doesn't mean that you can or should forget that you are making remote calls, it just means that you have less other unrelated plumbing to think about.
If you want to do RPC in a dynamic language over the web, NowJS is your model. The problem is that dynamic languages and statically typed languages have different requirements. I don't think that either SOAP or REST are a good solution to making the two styles work together on a web RPC. I think we need to work on that more.
I guess one more thing complicating this is the fact that most APIs (just like most software systems in general) are in fact dealing with the standard create, read, update, delete operations on data, with some variations. Batch updates are the most common variation, which you could actually easily extend the CRUD model for. The thing is, you almost always have important deviations from that where the CRUD model doesn't fit. But regardless of whether you are doing CRUD or something else, you still want your API to be as simple and normal as possible and that means RPC.
Maybe as some point we can focus more on languages or frameworks that better integrate the CRUD concept and things like calculated fields and aggregation, and transparently handle tasks like persistence and shared state.
Just about all of the programs I write need to persist their data and transmit/share their state. Maybe we want a semantic data oriented networking programming system (or more of them). This would be inspired by dynamic languages like JavaScript but necessarily incorporate some kind of typing more integrally (inferred?).
Maybe just start with NowJS, bake in some kind of CRUD generation based on nested schema definitions, put that on the server, add a way to indicate that operations need to be batched (for transactional consistency and practical network performance) and make the nice MongoDB criteria and now aggregation stuff baked into the client-side also. That would be cool (much cooler and more useful than me thinking or caring about HTTP PUT or DELETE).
A) is a noble idea but so far few people need to automatically discover and consume web services. B is the real issue: something like SOAP was necessary to make RPC possible over the web for typed languages like C# and Java.
REST was a counterargument made by some people coming from a dynamic languages standpoint who really didn't need as much information as the statically typed language people. Its too bad that people have taken A so seriously though and gotten confused or misled (probably deliberately) about what SOAP was for and then tried to make REST into that.
The most convenient and useful API, even over the web, is one that is as close to normal programming as possible. In other words, RPC-style (or some improvement on that like NowJS). That doesn't mean that you can or should forget that you are making remote calls, it just means that you have less other unrelated plumbing to think about.
If you want to do RPC in a dynamic language over the web, NowJS is your model. The problem is that dynamic languages and statically typed languages have different requirements. I don't think that either SOAP or REST are a good solution to making the two styles work together on a web RPC. I think we need to work on that more.
I guess one more thing complicating this is the fact that most APIs (just like most software systems in general) are in fact dealing with the standard create, read, update, delete operations on data, with some variations. Batch updates are the most common variation, which you could actually easily extend the CRUD model for. The thing is, you almost always have important deviations from that where the CRUD model doesn't fit. But regardless of whether you are doing CRUD or something else, you still want your API to be as simple and normal as possible and that means RPC.
Maybe as some point we can focus more on languages or frameworks that better integrate the CRUD concept and things like calculated fields and aggregation, and transparently handle tasks like persistence and shared state.
Just about all of the programs I write need to persist their data and transmit/share their state. Maybe we want a semantic data oriented networking programming system (or more of them). This would be inspired by dynamic languages like JavaScript but necessarily incorporate some kind of typing more integrally (inferred?).
Maybe just start with NowJS, bake in some kind of CRUD generation based on nested schema definitions, put that on the server, add a way to indicate that operations need to be batched (for transactional consistency and practical network performance) and make the nice MongoDB criteria and now aggregation stuff baked into the client-side also. That would be cool (much cooler and more useful than me thinking or caring about HTTP PUT or DELETE).