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.