ApiReportFetcher

ApiReportFetcher is reponsible for getting report from an API based on provided query.

Initialization

Api Client

To initialize ApiReportFetcher you need an instance of an API client to interact with an API. You can choose from built-in API clients or create your own.

from garf_core import ApiReportFetcher

report_fetcher = ApiReportFetcher(api_client)

Parser

Under the hood ApiReportFetcher fetches data from an API as list of dictionaries and tries to access elements in each dictionary via DictParser.

You can overwrite this behaviour by using one of built-in parsers or implementing your own.

Suppose you want to use NumericConverterDictParser to automatically convert strings to int/float whenever possible.

from garf_core import ApiReportFetcher
from garf_core.parsers import NumericConverterDictParser

report_fetcher = ApiReportFetcher(
  api_client=api_client,
  parser=NumericConverterDictParser
)

Built-in queries

Some queries for a particular API can be quite common so you want to create one or several built-in queries.

You can specified them in builtin_queries parameters during ApiReportFetcher initialization.

from garf_core import ApiReportFetcher
from garf_core.report import GarfReport
from garf_core.parsers import NumericConverterDictParser

def builtin_query(fetcher: ApiReportFetcher) -> GarfReport:
  return fetcher.fetch('SELECT field FROM resource')


builtin_queries = {'my_query': builtin_query}

report_fetcher = ApiReportFetcher(
  api_client=api_client,
  builtin_queries=builtin_queries
)

Fetching

To fetch data from an API use fetch method.

from garf_core import ApiReportFetcher

report_fetcher = ApiReportFetcher(api_client)
query = 'SELECT metric FROM resource'
report = report_fetcher.fetch(query)

fetch method returns GarfReport which can be processed in Python or written to local / remote storage.

Parametrization

If your query contains macros or templates, you need to pass values for them via args parameters.

from garf_core import ApiReportFetcher
from garf_core.query_editor import GarfQueryParameters

report_fetcher = ApiReportFetcher(api_client)

query = 'SELECT metric FROM resource WHERE dimension={dimension}'

query_parameters = GarfQueryParameters(
  macro={'dimension': 'value'},
  template={'dimension': 'value'},
)

report = report_fetcher.fetch(query, args=query_parameters)

Note

You can pass a dictionary instead of GarfQueryParameters.

query_parameters = {
  'macro': {
    'dimension': 'value',
  },
  'template': {
    'dimension': 'value',
  }
}

report = report_fetcher.fetch(query, args=query_parameters)

Built-in report fetchers

To simplify testing and working with REST APIs garf has two built-in report fetchers:

• FakeApiReportFetcher - simulates API response based on provided data
• RestApiReportFetcher - interacts with APIs with REST interface.

Fake

FakeApiReportFetcher is based on FakeApiClient.

It's ideal for prototyping and testing APIs without interacting with them directly.

from garf_core.fetchers import FakeApiReportFetcher

fake_data = [
  {'field1': {'subfield': 1}, 'field2': 2},
  {'field1': {'subfield': 10}, 'field2': 2},
]
report_fetcher = FakeApiReportFetcher.from_data(fake_data)

query = 'SELECT field1.subfield AS column FROM resource'
report = report_fetcher.fetch(query)

Note

Instead providing data directly you can use helper methods - from_json and from_csv:

report_fetcher = FakeApiReportFetcher.from_json('path/to/json')
report_fetcher = FakeApiReportFetcher.from_csv('path/to/csv')

Rest

RestApiReportFetcher is based on RestApiClient.

It's can be used with any API that provides REST interface.

You need to provide endpoint parameter which specifies root level address where API exists.

When writing queries specify relative address of the resource you want to fetch from (i.e. customers/1/orders).

from garf_core.fetchers import RestApiReportFetcher

endpoint= 'https://api.restful-api.dev'
report_fetcher = RestApiReportFetcher.from_endpoint(endpoint)

query = 'SELECT id FROM objects'
report = report_fetcher.fetch(query)