Countries By Region: Population Rankings

by Admin 41 views
Countries by Region: Population Rankings

Hey everyone! Today, we're diving into a cool project that lets you explore country populations within specific regions. This is super handy for anyone who needs to analyze regional demographics, whether you're a data analyst, policy maker, or just a curious individual. Let's break down the details, shall we?

Understanding the Goal

Our main aim is to build a REST endpoint that delivers a list of countries from a selected region, meticulously ordered by population in descending order. This means the most populous countries will be at the top of the list. We'll also handle ties in population by sorting alphabetically by country name. So, if two countries have the same population, the one with the earlier name in the alphabet comes first. This ensures a stable and predictable order.

Endpoint and Data

We'll be using the following endpoint: GET /api/v1/countries/region/{region}?order=population_desc. The {region} part is where you'll specify the area you're interested in, like "Western Europe" or "Eastern Asia." The ?order=population_desc part tells the system to sort the results as we discussed.

The data will come in a JSON array, and each item will represent a country with these fields:

  • code (STRING, ISO-3 country code)
  • name (STRING, country name)
  • continent (STRING, continent name)
  • region (STRING, region name)
  • population (INT, population count)
  • capital (STRING or null, capital city name)

Region Examples

You can use region names like: "Western Europe", "Eastern Asia", "Southern Europe", "Northern America", "Sub-Saharan Africa", "Caribbean", etc. Remember, the region names must match exactly what's in our dataset, case-insensitive.

Technical Deep Dive

Now, let's peek under the hood at the technical aspects of this project. It's crucial to ensure everything runs smoothly and efficiently.

Input Normalization

We'll handle the input with care. This means:

  • Trimming Spaces: We'll remove any extra spaces from the beginning or end of your region input.
  • Case-Insensitive Matching: We won't be sticklers for capitalization. "western europe" and "Western Europe" will both work.

Error Handling

We've also put in place a robust error-handling system:

  • Invalid Region: If you enter an incorrect region, like "Atlantis", you'll receive a 400 Bad Request error with a message showing some valid examples to guide you.
  • Unknown Path: If you try to access a non-existent path, like /api/v1/country/region/Western%20Europe, you'll get a 404 Not Found error.
  • No Data: If a region has no countries in our database, you'll get a 204 No Content response. This is an edge case, but it's important to handle it gracefully.

SQL Reference

For those who love SQL, here's the query we're using behind the scenes:

SELECT code,name,continent,region,population,capital
FROM country
WHERE region = :region
ORDER BY population DESC, name ASC;

Security

To keep things secure, we're using parameterized SQL to protect against SQL injection attacks.

Testing and Acceptance

We've set up a series of tests to ensure everything works as expected. These tests will cover various scenarios.

Test Scenarios

Here are some of the key tests we'll run:

  • Returns All Countries: Checks if the endpoint returns the correct countries for a region and verifies the descending population order, with ties sorted alphabetically by name.
  • Row Count Verification: Confirms that the number of returned countries matches what's expected based on a database query for the region.
  • Case-Insensitive and Trimmed Input: Validates that the endpoint correctly handles case-insensitive input and removes extra spaces.
  • Invalid Region Handling: Ensures that the system returns a 400 error when an invalid region is provided.
  • Unknown Path Handling: Makes sure the system returns a 404 error when an incorrect path is accessed.

Non-Functional Constraints and Project Details

Besides functionality, we're also focused on performance and efficiency.

Performance

  • Completion Time: The endpoint should respond within 1.5 seconds on a typical laptop or CI runner.
  • Memory Usage: It should use no more than 256 MB of heap memory.

Technical Aspects

  • JSON Responses: All responses will be in UTF-8 JSON format, as documented in our README.
  • Code Quality: We're using tools like Checkstyle, PMD, and CodeQL to ensure our code meets high-quality standards.

Project Status

  • The project is independent, negotiable, valuable, estimable, small, and testable (INVEST principles).
  • It's a P0 - Critical priority project.

We have also met the Definition of Done (DoD) criteria, including unit and integration tests, CI green status, code quality checks, updated README, and evidence screenshots.

Wrapping Up

This project will provide you with a powerful tool for analyzing regional populations. We hope this explanation helps you understand how it works and why it's valuable. Feel free to explore the API and see how it works! If you have any questions, don't hesitate to ask!