Feature Request: Add New Country API Routes

[StPfeffer]

Description

Addition of several new API routes to extend the existing functionality of our API. These new routes will provide users with more granular access to country and state information, improving the overall utility and flexibility of our API.

New Routes Related to Country

Get Country by Alpha-2 Code

• Endpoint: GET /api/v1/countries/alpha2/{code}
• Description: Retrieve details of a country using its ISO 3166-1 alpha-2 code.
• Example: GET /api/v1/countries/alpha2/us returns the details of the United States.

Get Country by Alpha-3 Code

• Endpoint: GET /api/v1/countries/alpha3/{code}
• Description: Retrieve details of a country using its ISO 3166-1 alpha-3 code.
• Example: GET /api/v1/countries/alpha3/usa returns the details of the United States.

Get Country by Numeric-3 Code

• Endpoint: GET /api/v1/countries/numeric3/{code}
• Description: Retrieve details of a country using its ISO 3166-1 numeric-3 code.
• Example: GET /api/v1/countries/numeric3/840 returns the details of the United States.

List All States for a Country by Country ID

• Endpoint: GET /api/v1/countries/:countryId/states
• Description: List all states or provinces for the country associated with the given country ID.
• Example: GET /api/v1/countries/:countryId/states lists all states in the United States.

List All States for a Country by Country Alpha-2 Code

• Endpoint: GET /api/v1/countries/alpha2/{code}/states
• Description: List all states or provinces for the country associated with the given country ISO 3166-1 alpha-2 code.
• Example: GET /api/v1/countries/alpha2/us/states lists all states in the United States.

List All States for a Country by Country Alpha-3 Code

• Endpoint: GET /api/v1/countries/alpha3/{code}/states
• Description: List all states or provinces for the country associated with the given country ISO 3166-1 alpha-2 code.
• Example: GET /api/v1/countries/alpha3/usa/states lists all states in the United States.

List All States for a Country by Country Numeric-3 Code

• Endpoint: GET /api/v1/countries/numeric3/{code}/states
• Description: List all states or provinces for the country associated with the given country ISO 3166-1 numeric-3 code.
• Example: GET /api/v1/countries/numeric3/840/states lists all states in the United States.

Rationale

The proposed new routes will significantly enhance the capabilities of our API by providing more specific endpoints for country and state information. These routes are particularly useful for applications that require detailed geographical data.

Impact

• Users: Developers using our API will have more endpoints to retrieve specific country and state information, making their applications more robust and data-rich.
• Performance: Proper indexing and optimization strategies will be needed to ensure these new routes perform efficiently.
• Documentation: The API documentation will need to be updated to include these new routes, along with examples and usage guidelines.

Additional Information

• These routes should adhere to RESTful API design principles.
• Include comprehensive error handling and validation.
• Provide appropriate documentation for each new route.

Acceptance Criteria

• All new routes are implemented as described.
• All routes pass unit and integration testing.
• Documentation is updated to include new routes and their usage