4 ms·

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"

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 14y ago
A YC company has a hypermedia-ish API: https://www.balancedpayments.com/docs/api?language=bash https://www.balancedpayments.com/docs/api?language=bash You can see links to the clients on the right.
user24 14y ago
You could use OPTIONS /somePath?
- fein 14y ago
  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 14y ago
    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 14y ago
      That's what resources that have form-style affordances offer. See, for example, Collection+JSON.
- caseysoftware 14y ago
  I built out a proof of concept on top of my open source project: https://github.com/caseysoftware/web2project-slim 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.

steveklabnik 14y ago

A YC company has a hypermedia-ish API: https://www.balancedpayments.com/docs/api?language=bash https://www.balancedpayments.com/docs/api?language=bash You can see links to the clients on the right.

user24 14y ago

You could use OPTIONS /somePath?

fein 14y ago
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 14y ago
  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 14y ago
    That's what resources that have form-style affordances offer. See, for example, Collection+JSON.
caseysoftware 14y ago
I built out a proof of concept on top of my open source project: https://github.com/caseysoftware/web2project-slim 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.