Update/documentation/extending last looks

[smithjw1]

This finishes my pass at the documentation for now.

Thanks all for the thoughtful reviews!

[chriszarate]

Mentioned on the other PR, but I don't think we should promote this pattern. It constrains us in future changes and this alternate approach is unnecessary. They can just hold a reference to some_identifier in their own code and pass it in via use(). This should definitely not be idiomatic.

[smithjw1]

When I look at the Airtable Data Source we add a base property to the data source definition, that's was my inspiration.

I think your suggesting that additional configuration should happen outside of service_config, so something like:

$data_source = HttpDataSource::from_array( [
    'service_config' => [
        '__version' => 1,
        'display_name' => 'More Complicated Example API',
        'endpoint' => 'https://api.complexexample.com/',
        'request_headers' => [
            'Content-Type' => 'application/json',
            'X-Api-Key' => MY_API_KEY_CONSTANT,
        ],
    ],
] );

$my_config = [
 'some_identifier' => 'id-123'
]

$zipcode_query = HttpQuery::from_array( [
    'data_source' => $data_source,
    'endpoint' => function ( array $input_variables ) use ( $data_source, $my_config ): string {
        return  return $data_source->get_endpoint() . $my_config['some_identifier'] . "/" . $input_variables['search'];
    },
])

[chriszarate]

Yes, exactly

[chriszarate]

I applied your suggestion in a781b4c