Internal Design

Welcome to HvPy's design wiki. These pages will be useful for you if you're a developer for HvPy or if you're looking to make changes to it.

Overview

HvPy is a python interface for interacting with Heliovewer's Web API. This means all API calls are done via sending an HTTP request and parsing the response. Since this action is common for all API requests, it is encapsulated by the API core in HvPy. Certain parameters are provided to the core via an instance of HvpyParameters. This instance contains all information necessary to perform the API request. It contains the target URL, the input parameters, and the expected output type. Using this information, the HTTP Requester will be able to perform the request and coerce the result into the desired type.

Request Flow

Each request starts with a set of Input Parameters. The HvpyParameters class defines the metadata needed for an API request. It contains the input parameters, API URL, and the expected output type for the request. Using this information, the module core may take that information to perform the HTTP request and parse the result into the expected type.

Input Parameters

In order to handle input validation and to define the parameters for each endpoint, we've chosen to use pydantic to handle definitions for API input parameters.

Every API endpoint has an InputParameters class which will inherit HvpyParameters. These classes use pydantic to construct and validate the user's input parameters. These classes are converted into dictionaries via a call to InputParameters.dict() and the resulting dictionary is passed to the requests library to send off the API request.

Note: An instance of HvpyParameters behaves much like a dictionary, and may be passed directly to the requests module as-is. However, to have more control over the input parameters, and to overcome some limitations of pydantic (mainly allowing "json" to be a field name), we have chosen to use dict() as a way to extract and manipulate the fields as-needed.

HvpyParameters defines this dict() function, and defines the interface to be used for all input parameter classes.

Sometimes the output type may change depending on one of the input parameters. For example, see getJP2Image where the output may be binary, text, or JSON, depending on the input parameters. To handle this, HvpyParameters defines a function get_output_type() which will return the expected result type. By default, this function will return OutputType.Raw. Subclasses may override this to their desired output type. Options for OutputType follow.

OutputType.RAW

Raw is best used for binary data. The result from the API is given directly to the user.

OutputType.JSON

The JSON from the api response will be parsed into a python dictionary representing the json data.

OutputType.STRING

The result from the API will be parsed as a utf-8 encoded string and will be returned as type str

Directory Structure

Front End vs. Back End

Much of the design mentioned above is for internal use when adding new API endpoints or modifying internal behavior of this module. The internal design allows for ease of adding new APIs, validating input parameters, and keeping the code DRY.

The actual front end that users will interface with lives in facade.py as it is the façade that hides this internal design. This module contains the API interface in it's simplest form. It is responsible for taking user input, constructing the HvpyParameters instance and passing it along to the core to perform the request. All this is expected to be roughly 3-4 lines of code to accomplish for each API endpoint.

hvpy
|-- __init__.py             # Exposes API functions and parameter classes
|-- core.py                 # Contains the API Requester which handles all HTTP I/O
|-- facade.py               # Defines the front-end calls for the API functions
|-- io.py                   # Contains the base InputParameters class and OutputType enum
|-- parameters.py           # Contains imports of the endpoint class
|-- utils.py                # Contains functions that are reused in multiple endpoints
|-- api_groups              # Analogous to the Web API's api groups
    |-- jpeg2000            # Groups JPEG2000 API endpoints together
        |-- get_jp2_image.py  # Contains I/O parameters for getJp2Image
        |-- get_jp2_header.py # Contains I/O parameters for getJp2Header
        |-- etc...
    |-- movies
        |-- queue_movie.py   # Contains I/O parameters for queueMovie
        |-- etc...
    |-- etc... # See https://api.helioviewer.org/docs/v2/api/index.html for all API groups