The new trend in applications (and API) is all about on-demand and self-service. Web 2.0 (Cloud) applications are more adaptable and powerful. Being able to integrate applications quickly will be key to their success. If you're only providing hard-coded documentation, then you're a speed bump to your application's success.
Exposing a set of standard metadata API for your APIs will allow developers to build tools to auto-magically consume your APIs and keep up with changes much more efficiently. Integration tool vendors often write connectors for applications which allows them to expose the various API in a standard way in their tools. Customers then use those tools to build out their integrations without having to worry about the low level details of every API call they plan to use. If you expose a standard set of APIs that would allow these tools to auto-discover your APIs and auto-react to changes in your application schema and services, your API consumers will love you for it!
When WSDLs were created, every one cheered for the fact that there was a standard way to describe interfaces. You can programmatically consume it and the very least, create stubs to provide/consume the service. It made getting started easier. Unfortunately, most implementation that I encountered only offered statically generated WSDLs that either only changed when the application was upgraded or required frequent exporting/importing to capture on-demand customizations. Painful at best. Now we have REST-ful services which are easier(?) to consume but you 1st have to read the often lengthy documentation to get started. I don't see anyone running to support WADL (WSDL equivalent for Rest-ful services). Do we need another static interface definition?
Forget WSDLs and WADLs! I propose, we create a standard metadata API for APIs (API4API). The key is to keep it simple so it will be adopted. All it needs to do is to describe objects and services you're planning to expose. For every service, defines the inputs and outputs. If you add more objects or services, a simple call would reveal them. It should also indicate the Authentication methods that are supported (e.g. Basic Auth, OAuth).If your applications are evolving, If your application are customizable, then you need to give developers the ability to create dynamic integrations to keep up.
