What is Google API Discovery?

Question

I am having trouble understanding the concept of “API discovery” as used in Google products/services. Here’s some Python code that uses the said discovery service to access Google Cloud Vision:

from googleapiclient.discovery import build
from oauth2client.client import GoogleCredentials
… 
API_DISCOVERY_FILE = 'https://vision.googleapis.com/$discovery/rest?version=v1'
hlh = httplib2.Http()
credentials = GoogleCredentials.get_application_default().create_scoped(
    ['https://www.googleapis.com/auth/cloud-platform'])
credentials.authorize(hlh)
service = build(serviceName='vision', version='v1', http=hlh, discoveryServiceUrl=API_DISCOVERY_FILE)
service_request = service.images().annotate(body={ <more JSON code here> })

Here’s another bit of Python code that also accesses Google Cloud Vision, but does not use API discovery and works just fine:

import requests
…
ENDPOINT_URL = 'https://vision.googleapis.com/v1/images:annotate'
response = requests.post(ENDPOINT_URL,
    data=make_image_data(image_filenames),
    params={'key': api_key},
    headers={'Content-Type': 'application/json'})

What I can’t wrap my head around is this question: You need to know the details of the API that you are going to be calling so that you can tailor the call; this is obvious. So, how would API discovery help you at the time of the call, after you have already prepared the code for calling that API?

PS: I did look at the following resources prior to posting this question:
https://developers.google.com/discovery/v1/getting_started
https://developers.google.com/discovery/v1/using
I did see this answered question but would appreciate additional insight.

Answer 1

Note: I lack the knowledge of the Google API you are mentioning.

You need to know the details of the API that you are going to be calling so that you can tailor the call; this is obvious.

In theory to me this is only required for the very first call, which would be the call to a starting service which would for instance list a number of resources. From there on you can have branches to underlying resources and their allowed methods (verbs if you will). So this example illustrated a tree like structure. If you provide a GUI to navigate through this discoverability in a generic way, a person would then be able to decide what to do.

In practice this is kind of hard to do once you have vast amounts of resources and all sorts of interrelationships between them.