[sopooneo]

I agree. The promise of REST APIs is that will be self describing, but for that benefit to be realized, we need general purpose REST clients that can "discover" everything they need to know given just a root uri. Are there any such clients? And no, web browsers do not count.

[steveklabnik]

A YC company has a hypermedia-ish API: https://www.balancedpayments.com/docs/api?language=bash

You can see links to the clients on the right.

[user24]

You could use

OPTIONS /somePath?

[caseysoftware]

I built out a proof of concept on top of my open source project:

https://github.com/caseysoftware/web2project-slim

But one of the things I did a little differently is that instead of writing the code and then the docs separately, I pass the validation information from the object itself.. so the API layer doesn't have to know any of it in advance. It can pass that along to the end clients.

I'm not convinced this is the solution but it mostly works for now and would love any & all feedback.

My next proof of concept will be to use Javascript to retrieve the required fields and decorate a simple html form.

[fein]

Thank you for being realistic.

REST means more than just GET, POST, PUT, DELETE.

Some may make the excuse that call OPTIONS /path isn't straightforward, but I have no clue how you could get more obvious than that.

[thawt]

The problem with OPTIONS is it doesn't describe anything about the data the resource returns.

I really wish there was a DESCRIBE verb that would return a structure of what is expected to be received/sent.

Then microformats could spring up around datatypes returned by DESCRIBE. This is of course very XML.

Edit: This would also allow for automatic discovery of new APIs.

[steveklabnik]

That's what resources that have form-style affordances offer. See, for example, Collection+JSON.