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 so that it knows which parameters to send and receive. The general flow for an API request is shown in this diagram.

API Parameters

The API parameters and responses will be different for every API endpoint. In order to be able to generically handle any Input/Output parameters, we've chosen to use pydantic to handle constructing and validating our input parameters.

Input Parameters

Every API endpoint has an InputParameters class. 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.

Output Parameters

Since every API endpoint may have a different kind of response (binary, string, json, etc.) the API must decide how to handle the result request. To handle this there shall be an enum OutputType which will be passed to the API Requester so it knows how to return the result.

Some API endpoints return a different result depending on the input parameters provided. Because of this, the InputParameters class shall have a function get_output_type() for internal use which will determine how the output will be handled.

Some examples for response handling follow:

OutputType.Raw

Raw is best used for strings or binary data. The result from the API is given directly to the user. This is expected to be the most common use case.

OutputType.Json

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

OutputType.File

The resulting data will be saved to a file specified in the input parameters

Directory Structure

hvpy
|-- __init__.py             # Exposes API functions and parameter classes
|-- core.py                 # Contains the API Requester which handles all HTTP I/O
|-- io.py                   # Contains the base InputParameters class and OutputType enum
|-- api_groups              # Analogous to the Web API's api groups
    |-- jpeg2000            # Groups JPEG2000 API endpoints together
        |-- getJp2Image.py  # Contains I/O parameters for getJp2Image
        |-- getJp2Header.py # Contains I/O parameters for getJp2Header
        |-- etc...
    |-- movies
        |-- queueMovie.py   # Contains I/O parameters for queueMovie
        |-- etc...
    |-- etc... # See https://api.helioviewer.org/docs/v2/api/index.html for all API groups