The API Endpoints

Purpose of this page

List every endpoint this API exposes, who's allowed to call it, and what a request and response look like for each.

Resources at a glance the map

Every request other than /api/auth/register, /api/auth/login, and /health needs an Authorization: Bearer <token> header. Without one, every endpoint below responds 401 Unauthorized before any of its own logic runs — see Section 2 to get a token.

/health metals_api/app.py

The one route defined directly in app.py rather than a blueprint — no /api prefix, no authentication, and deliberately no database access. It returns {"status":"ok"} with 200 whenever the HTTP server is running.

/api/elements metals_api/routes/element_routes.py

Chemical elements, keyed by atomic number.

{
  "atomic_number": 3,
  "name": "Lithium",
  "symbol": "Li",
  "melting_point_f": 356.9,
  "boiling_point_f": 2447.6,
  "color": "silvery",
  "density": 0.53,
  "category": "ALKALI_METAL",
  "state_at_room_temp": "SOLID",
  "is_toxic": false,
  "is_magnetic": false,
  "common_uses": "batteries"
}

{
  "atomic_number": 3,
  "name": "Lithium",
  "symbol": "Li",
  "melting_point_f": 356.9,
  "boiling_point_f": 2447.6,
  "color": "silvery",
  "density": 0.53,
  "category": "ALKALI_METAL",
  "state_at_room_temp": "SOLID",
  "is_toxic": false,
  "is_magnetic": false,
  "common_uses": "batteries"
}

/api/alloys metals_api/routes/alloy_routes.py

Named mixtures, like “Sterling Silver.”

// POST /api/alloys
{ "name": "Fine Gold 24K", "color": "gold", "description": "High-purity investment gold." }

/api/alloy-elements metals_api/routes/alloy_element_routes.py

The join table between alloys and elements — what percentage of a given alloy each element makes up. This is the one resource identified by two path values instead of one, matching its composite primary key.

// POST /api/alloy-elements
{ "alloy_id": 6, "atomic_number": 47, "percent_of_alloy": 92.5 }

/api/coins metals_api/routes/coin_routes.py

Real-world coins, each minted from exactly one alloy.

// POST /api/coins
{
  "name": "American Gold Eagle (1 oz)",
  "country": "United States",
  "mint": "United States Mint",
  "year_introduced": 1986,
  "alloy_id": 2,
  "gross_weight_g": 33.9305,
  "face_value": 50.00,
  "face_value_currency_code": "USD"
}

How errors are reported consistent across every endpoint

Every route validates the request before touching the database, then lets the service layer enforce business rules. Both layers report problems the same way, so client code only needs to handle one shape of error response.

Notice the field name differs by cause: validation and business-rule failures use errors (plural, an array — there can be more than one), while authentication, authorization, and not-found failures use error (singular, a string).