Suppose a unit converter has a screen for choosing units and a separate piece of code that calculates the answer. The screen needs to ask for a conversion without knowing how the calculation works. An application programming interface (API) is the contract that defines how those pieces interact. Like a restaurant menu connecting an order-taker and a kitchen, it lets either side change its internal work while preserving the agreed way to make requests. section 3.6.2
For a unit converter, the backend contract consists of three Python functions:
- list_quantities() returns the available kinds of measurement. section 3.6.2
- list_units(quantity_name) returns the units available for a chosen quantity. section 3.6.2
- convert_value(quantity_name, from_unit_name, to_unit_name, value) performs a conversion and returns a Result containing the input and output values and units. section 3.6.2
The same idea applies when the other component belongs to someone else. A to-do app could fetch a joke from a public API rather than store jokes in its own code. To learn what an external API accepts, read its documentation: its developer chooses the contract. A web request commonly uses a base address and an endpoint; requests may also carry parameters, a payload, or an API key in HTTP headers. section 5.3 section 5.3.1
Listing 3.6 The backend functions in backend.py
from unit_config import unit_config
from result import Result
from typing import List
def list_quantities() -> List[str]:
return list(unit_config.keys())
def list_units(quantity_name) -> List[str]:
return list(unit_config[quantity_name].units.keys())
def convert_value(
quantity_name: str,
from_unit_name: str,
to_unit_name: str,
value: float) -> Result:
quantity = unit_config[quantity_name]
from_unit = quantity.units[from_unit_name]
to_unit = quantity.units[to_unit_name]
# Two-step conversion: from-unit to standard unit, then to-unit
value_in_to_units = (value *
from_unit.value_in_std_units /
to_unit.value_in_std_units)
return Result(from_unit, to_unit, value, value_in_to_units)
The three backend functions show a small API in code: each function exposes a specific action while keeping unit configuration and conversion logic behind the interface. section 3.6.2
An API key is part of the request contract
A request to the dad-joke endpoint can return “Missing API Key.” That response is a clue to check the service’s documented request requirements rather than hardcode jokes or change the app’s conversion-style interface. section 5.3.1
