A country carries its own states list
Populate a state or province picker with one request using the country the user has already selected.
Once someone selects a country in a form, the next question is often their state or province. You've already got the country code, so that should be enough to fetch the next list.
GET /country/DE/states returns Germany's subdivisions. These are the first two entries:
{
"country": "DE",
"states": [
{ "state": "BW", "name": "Baden-Württemberg", "type": "land" },
{ "state": "BY", "name": "Bavaria", "type": "land" }
]
}
The list is its own request under the country route. You don't need to search all states or maintain a separate country-to-state mapping in your application.
Use name for the option label and keep state as its value. The type field preserves the subdivision's kind, since the things we put in a "state" picker aren't called states in every country.
If the user chooses Bavaria and you need its full record, call /state/BY?country=DE. Carry the country code forward along with the state code. Short subdivision codes can repeat across countries, and your form already has the context needed to make the next lookup unambiguous.