I am dumbfounded I haven’t heard of this service before, it’s pretty clever. Anyone familiar with WSDL or Soap is going to instantly grok this.
For example, here’s the Google Analytics API discovery document https://www.googleapis.com/discovery/v1/apis/analytics/v3/rest
With this data set, it’s relatively trivial to auto-generate an interface / command pattern instance to make the user feel like they’re actually using the API directly. Furthermore the discovery document provides a fairly good reference breakdown of required arguments, argument types, and basic validation type hints to developers.
A trivial example, here’s how to grab the first profile for the currently authenticated user in analytics:
analytics = client.discovered_api("analytics",'v3') #Grab the first profile result = client.execute(analytics.management.accounts.list) print result.data.items
Until I called discover on analytics, my client had no idea how to deal with the Analytics API, but now it not only knows how to work with the remote service but can provide basic validations, some advanced error handling ( bad/wrong input, connectivity issues) and in an interactive console in Ruby or Python I can explorer the api as needed.