Request data from remote API server

request_api_server(url, params=None, headers=None, timeout=None, stream=False)

Connect to an API server given configuration and return a Response object.

This is a wrapper around the get function from the requests package. I use this to query various remote biology databases with APIs, for instance, Varsome, Ensembl, GTEx, cBioPortal, etc.

Examples:

Let us query the Varsome API server to annotate a variant with ACMG information. Varsome requires API token to use the service. Provide an API token inside the HTTP header; otherwise, you can only run one API query once per day. The specific variant used here is from https://api.varsome.com/.

>>> from tinyscibio import request_api_server
>>> api_server_url = "https://api.varsome.com/lookup/"
>>> qry = "15-73027478-T-C"
>>> lookup_path = f"{api_server_url}{qry}"
>>> qry_params = {
        "add_ACMG_annotation": 1
    }
>>> headers = {"Accept": "application/json"}
>>> response = request_api_server(
        lookup_path,
        qry_params,
        headers
    )
>>> assert response.status_code == 200  # if the connection is success

Parameters:

Name	Type	Description	Default
url	str	lookup path (not just the API server URL).	required
params	Optional[_RequestParamsType]	query parameters to defined what you want to request.	None
headers	Optional[_RequestHeaderType]	HTTP headers.	None
timeout	Optional[float]	How many seconds to wait for the server to send data before giving up.	None
stream	bool	Whether or not getting response data immediately.	False

Returns:

Type	Description
Response	A requests.Response object.

Raises:

Type	Description
HTTPError	When HTTP error occurred.
Timeout	When request timed out.
ConnectionError	When connection error occurred.
RequestException	All other errors not covered by the above ones.