[caseysoftware]

I think separating the documentation step (machine-readable or not) from the actual development process is what makes the entire process painful. It means you have to have parallel development or things get out of sync pretty easily.

I've sketched out some work on using OPTIONS and having the code introspect itself to describe how to interact with the API. Basically with good validation, error messages, and solid/consistent naming conventions, you can take it a long way before you have to step out of the development that you're already doing.

[alpinegizmo]

I suggest you look at the work on "interface driven development" with swagger: https://groups.google.com/forum/#!msg/swagger-swaggersocket/...

There's plenty that API providers can do to make things saner for all of us, and themselves. Problem is, many (if not most) of them don't seem to care enough. As users of APIs we are their customers, and we outnumber them. Let's find a way to show them the benefits of making our lives easier.