### GET /v4/all Request Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Example of a GET request to retrieve all countries, specifying desired fields.

```http
GET /v4/all?fields=name,capital,region,geolocation
```

--------------------------------

### GET /v4/all Response (200 OK) Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Example JSON response for a successful request to retrieve all countries with specified fields.

```json
[
  {
    "name": {
      "common": "Åland Islands",
      "official": "Åland Islands",
      "nativeName": [
        {
          "lang": "swe",
          "official": "Autonoma landskapet Åland",
          "common": "Åland"
        }
      ]
    },
    "capital": ["Mariehamn"],
    "region": "Europe",
    "geolocation": {
      "latitude": 60.117,
      "longitude": 19.867
    }
  },
  {...}
]
```

--------------------------------

### Running the Application

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

This example shows how to run the Micronaut application from the command line using the compiled JAR file. The server will typically start on port 8080.

```bash
java -cp target/restcountries.jar com.restcountries.Application
# Server running on http://localhost:8080
```

--------------------------------

### Example GET Requests for Sovereign State Search

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Shows how to query for territories belonging to a sovereign state, with an example of field filtering.

```HTTP
GET /v4/sovereignstate/GBR
```

```HTTP
GET /v4/sovereignstate/DNK?fields=name,capital,sovereignState
```

--------------------------------

### Example GET Requests for Translation Search

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Demonstrates how to call the getByTranslation endpoint with and without the fields parameter.

```HTTP
GET /v4/translation/deutschland
```

```HTTP
GET /v4/translation/españa?fields=name,translations,region
```

--------------------------------

### Micronaut Controller Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

This Java example demonstrates a Micronaut controller for the /v4/ API version, defining a GET endpoint for retrieving country data by alpha code and optionally filtering fields.

```java
@Controller("/v4/")
public class CountryControllerV4 {
    @Get("alpha/{alphacode}")
    @Schema(name = "RestCountries")
    public Object getByAlpha(@PathVariable("alphacode") String alpha,
                             @QueryValue("fields") Optional<String> fields) {
        // ...
    }
}
```

--------------------------------

### GET /v4/alpha/ Request Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Example of a GET request to retrieve multiple countries using a comma-separated list of alpha codes and optional field filtering.

```http
GET /v4/alpha/?codes=CO,PE,VE
```

--------------------------------

### Example GET Requests for Independence Status Filter

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Demonstrates calls to filter countries by independence status, including specifying status and fields.

```HTTP
GET /v4/independent
```

```HTTP
GET /v4/independent?status=false
```

```HTTP
GET /v4/independent?status=true&fields=name,capital,hdi
```

--------------------------------

### GET /v4/alpha/{alphacode} Request Examples

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Examples of GET requests to retrieve a single country by its alpha code (CCA2, CCN3, CCA3, or CIOC), with and without field filtering.

```http
GET /v4/alpha/CO
```

```http
GET /v4/alpha/col
```

```http
GET /v4/alpha/170
```

```http
GET /v4/alpha/CO?fields=name,capital,gdp
```

--------------------------------

### GET /v4/alpha/{alphacode} Response (200 OK) Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Example JSON response for a successful request to retrieve a single country by its alpha code, including specified fields.

```json
{
  "name": {
    "common": "Colombia",
    "official": "Republic of Colombia",
    "nativeName": [...]
  },
  "capital": ["Bogotá"],
  "gdp": {
    "total": 314326000000,
    "perCapita": 6044
  }
}
```

--------------------------------

### Example application.yml Configuration

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Illustrates typical configuration settings for a Micronaut application, including application name, server port and host, HTTP client read timeout, and logger levels.

```yaml
micronaut:
  application:
    name: restcountries
  server:
    port: 8080
    host: 0.0.0.0
  http:
    client:
      read-timeout: 30s

logger:
  levels:
    com.restcountries: INFO
    io.micronaut: INFO
    root: WARN
```

--------------------------------

### REST Countries API V4 General Endpoint Examples

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

These examples demonstrate common V4 endpoint paths, which are direct equivalents to V3.1 paths with the base path changed from /v3.1/ to /v4/. Use these for general country data retrieval.

```http
GET /v4/all?fields=name,capital
GET /v4/name/Germany
GET /v4/alpha/CO
GET /v4/currency/USD
GET /v4/capital/Berlin
GET /v4/region/Europe
GET /v4/subregion/Northern Europe
GET /v4/lang/english
GET /v4/demonym/german
GET /v4/translation/deutschland
GET /v4/independent?status=true
```

--------------------------------

### NativeName Example (v3.1)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/types.md

An example JSON object illustrating the structure of the nativeName field, showing Danish native names.

```json
{
  "nativeName": {
    "dan": {
      "official": "Kongeriget Danmark",
      "common": "Danmark"
    }
  }
}
```

--------------------------------

### Main Application Class

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

The entry point for starting the Micronaut application and initializing the HTTP server. This class is essential for running the application.

```java
public class Application {
    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
    }
}
```

--------------------------------

### Idd Example Usage

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/types.md

An example JSON object representing international dialing information.

```json
{
  "root": "+1",
  "suffixes": ["876"]
}
```

--------------------------------

### Main Method Signature

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

The static main method is the entry point for the JVM to start the Micronaut application. It initializes the framework and runs the application.

```java
public static void main(String[] args) {
    Micronaut.run(Application.class, args);
}
```

--------------------------------

### Run Docker Container

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Start a Docker container from the built image, mapping port 8080 on the host to port 8080 in the container. This allows accessing the application from the host machine.

```bash
docker run -p 8080:8080 restcountries
```

--------------------------------

### Field Filtering Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Illustrates how to use the `fields` query parameter to limit the response data for the `/all` endpoint. Invalid field names will result in a 400 Bad Request.

```http
GET /v3.1/all?fields=name,capital,population
```

--------------------------------

### Full Application Class Definition

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

The complete definition of the Application class, which is minimal and relies on Micronaut's convention-over-configuration for setup. Configuration can be externalized to YAML or properties files.

```java
package com.restcountries;

import io.micronaut.runtime.Micronaut;

public class Application {
    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
    }
}
```

--------------------------------

### Checking Java Version

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Command to verify the installed Java Development Kit version, ensuring it meets the application's requirements (Java 17+).

```bash
java -version
```

--------------------------------

### Example JSON Response for Sovereign State Search

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Illustrates the structure of a successful JSON response when searching for territories under a sovereign state.

```JSON
[
  {
    "name": {
      "common": "Greenland",
      "official": "Kalaallit Nunaat"
    },
    "capital": ["Nuuk"],
    "sovereignState": "DNK"
  },
  {
    "name": {
      "common": "Faroe Islands",
      "official": "Faroe Islands"
    },
    "capital": ["Tórshavn"],
    "sovereignState": "DNK"
  }
]
```

--------------------------------

### V3.1 HTTP Controller Reference

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Documentation for the V3.1 HTTP controller, detailing public methods, parameters, return types, error conditions, and example requests/responses.

```APIDOC
## CountryControllerV31

### Description
Documentation for the V3.1 HTTP controller, detailing public methods, parameters, return types, error conditions, and example requests/responses.

### Methods
- 13 public methods with full signatures
- Parameter tables for each method
- Return types and error conditions
- Example requests and responses
- HTTP routing annotations
```

--------------------------------

### Field Filtering Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Demonstrates how to use the 'fields' parameter to request specific data points from the API. The parameter accepts a comma-separated list of field names, with a maximum of 10 fields per request.

```url
/all?fields=name,capital
```

--------------------------------

### Retrieve all countries with specified fields

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Endpoint to get all countries, requiring the 'fields' parameter to be specified.

```HTTP
/v3.1/all?fields=name,flags
```

--------------------------------

### JSON Serialization Output Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

The resulting JSON output after serializing a Java Country object. This demonstrates the structure and fields included in the JSON response.

```json
{
  "name": {
    "common": "Germany",
    "official": "Federal Republic of Germany",
    "nativeName": [...]
  },
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€"
    }
  ]
}
```

--------------------------------

### Get country by name

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Retrieve information for a specific country using its name.

```HTTP
https://restcountries.com/v3.1/name/peru
```

--------------------------------

### REST Countries API V4 Sovereign State Endpoint Example

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

This example shows how to use the V4-specific endpoint to search for countries governed by a particular sovereign state using its CCA3 code. Ensure the provided cca3 code is exactly 3 characters long.

```http
GET /v4/sovereignstate/GBR
```

--------------------------------

### Get Country by Name (V3.1)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Instantiates the V3.1 country service and retrieves countries by name. Services are thread-safe and cache data in memory after the first load.

```java
CountryServiceV31 service = CountryServiceV31.getInstance();
Set<Country> results = service.getByName("France", false);
```

--------------------------------

### Get all countries (filtered by fields)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Retrieve all countries, specifying the desired fields to limit the response size. This is a mandatory step for the 'all' endpoint.

```HTTP
https://restcountries.com/v3.1/all?fields=name,capital,currencies
```

--------------------------------

### GET /v3.1/all

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Retrieves all countries. This endpoint requires the `fields` query parameter to filter the response, specifying which country attributes to include. Omitting `fields` will result in a 400 Bad Request.

```APIDOC
## GET /v3.1/all

### Description
Returns all countries. **Requires `fields` parameter.**

### Method
GET

### Endpoint
/v3.1/all

### Parameters
#### Query Parameters
- **fields** (string) - Required - Comma-separated field names, max 10 per request.

### Request Example
```
GET /v3.1/all?fields=name,capital,region
```

### Response
#### Success Response (200)
- Array of Country objects (v3.1)

#### Response Example
```json
[
  {
    "name": {
      "common": "Afghanistan",
      "official": "Islamic Emirate of Afghanistan",
      "nativeName": {
        "prs": {
          "official": "...",
          "common": "..."
        }
      }
    },
    "capital": ["Kabul"],
    "region": "Asia"
  }
]
```
```

--------------------------------

### GET /v3.1/name/{name}

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Searches for countries by their name, matching against both common and official names. The `fullText` parameter can be used for exact matching, while `fields` can filter the returned data.

```APIDOC
## GET /v3.1/name/{name}

### Description
Search countries by name. Searches both common and official names.

### Method
GET

### Endpoint
/v3.1/name/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Country name to search.

#### Query Parameters
- **fullText** (boolean) - Optional - If true, performs an exact match against common or official name only. Defaults to false (substring search).
- **fields** (string) - Optional - Comma-separated field names to include in the response.

### Request Example
```
GET /v3.1/name/Germany
GET /v3.1/name/eesti?fullText=true
GET /v3.1/name/united?fields=name,capital
```

### Response
#### Success Response (200)
- Array of matching Country objects

#### Response Example
(Response structure similar to /all endpoint, but filtered by name)
```

--------------------------------

### Get Singleton Instance of CountryServiceV4

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Retrieve the singleton instance of CountryServiceV4. The first call initializes the service by loading all countries from JSON into memory. Subsequent calls return the cached instance. This method is thread-safe.

```java
CountryServiceV4 service = CountryServiceV4.getInstance();
Set<Country> allCountries = service.getAll();
```

--------------------------------

### HTTP Endpoint Mapping (V3.1)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Demonstrates how Micronaut annotations map HTTP GET requests to controller methods for the V3.1 API. Supports path variables and optional query parameters.

```java
@Controller("/v3.1/")
public class CountryControllerV31 {
    @Get("alpha/{alphacode}")
    public Object getByAlpha(@PathVariable("alphacode") String alpha, 
                             @QueryValue("fields") Optional<String> fields) { ... }
```

--------------------------------

### Get All European Countries with Basic Info

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Retrieves a list of all countries in the 'Europe' region, including their name, capital, and population. The search is case-insensitive and supports substring matching for names.

```APIDOC
## GET /v3.1/region/Europe?fields=name,capital,population

### Description
Retrieves a list of all countries in the 'Europe' region, including their name, capital, and population. The search is case-insensitive and supports substring matching for names.

### Method
GET

### Endpoint
/v3.1/region/Europe

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies the fields to include in the response. Example: `name,capital,population`

### Response
#### Success Response (200)
- **name** (object) - Contains common, official, and native names of the country.
- **capital** (array) - An array of strings representing the capital city/cities.
- **population** (integer) - The population of the country.

#### Response Example
{
  "example": "[\n  {\n    \"name\": {\n      \"common\": \"Germany\",\n      \"official\": \"Federal Republic of Germany\",\n      \"nativeName\": {...}\n    },\n    \"capital\": [\"Berlin\"],\n    \"population\": 83370000\n  },\n  {\"...\"}\n]"
}
```

--------------------------------

### Search by Name (Substring Match)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

This HTTP GET request performs a substring search for countries whose names contain 'united'. It requests the common name and region. The response is a JSON array of matching countries.

```http
GET /v3.1/name/united?fields=name,region
```

```json
[
  {
    "name": {"common": "United States", "official": "..."},
    "region": "Americas"
  },
  {
    "name": {"common": "United Kingdom", "official": "..."},
    "region": "Europe"
  },
  {
    "name": {"common": "United Arab Emirates", "official": "..."},
    "region": "Asia"
  }
]
```

--------------------------------

### Netty Server Configuration Override

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Example of overriding Netty HTTP server and client settings in application.yml. This configuration adjusts max content length and request size, and sets the number of Netty worker threads.

```yaml
micronaut:
  http:
    client:
      max-content-length: 10485760  # 10 MB
    server:
      max-request-size: 10485760
      netty:
        worker:
          threads: 4
```

--------------------------------

### Package Application for Production

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Build an optimized JAR file for production deployment using the Maven wrapper. Tests are skipped during this packaging process.

```bash
./mvnw clean package -DskipTests
```

--------------------------------

### Build and Run Docker Image

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Build a Docker image for the application and run it on port 8080. The Dockerfile is located in the project root.

```dockerfile
FROM openjdk:17
COPY target/restcountries-2025.04.20.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]
```

```bash
docker build -t restcountries .
docker run -p 8080:8080 restcountries
```

--------------------------------

### Setting Server Port via Environment Variable

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Shows how to configure the server port using an environment variable, which is a high-priority configuration source.

```bash
MICRONAUT_SERVER_PORT=8081
```

--------------------------------

### Build Docker Image

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Create a Docker image for the application using the provided Dockerfile. This image can then be used to run the application in a containerized environment.

```bash
docker build -t restcountries .
```

--------------------------------

### Get All European Countries with Basic Info

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

This HTTP GET request retrieves all countries in Europe, including only their name, capital, and population. The response is a JSON array of country objects.

```http
GET /v3.1/region/Europe?fields=name,capital,population
```

```json
[
  {
    "name": {
      "common": "Germany",
      "official": "Federal Republic of Germany",
      "nativeName": {...}
    },
    "capital": ["Berlin"],
    "population": 83370000
  },
  {"..."}
]
```

--------------------------------

### Local Development Configuration

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Configure application settings for local development, including server port, host, read timeout, and logging levels. Create this file in src/main/resources.

```yaml
micronaut:
  application:
    name: restcountries
  server:
    port: 8080
    host: 0.0.0.0
  http:
    client:
      read-timeout: 30s

logger:
  levels:
    com.restcountries: DEBUG
    io.micronaut: INFO
```

--------------------------------

### Filter Countries by Independence Status

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Filters countries based on their independence status. Use 'true' to get independent countries and 'false' to get non-independent territories. Null independence values are treated as false.

```java
Set<Country> independent = service.getIndependent(true);
Set<Country> territories = service.getIndependent(false);
```

--------------------------------

### Get country by code

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Retrieve information for a specific country using its alpha code.

```HTTP
https://restcountries.com/v3.1/alpha/co
```

--------------------------------

### Build with Maven Wrapper

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Use the Maven wrapper scripts for consistent and reproducible builds across different environments. The wrapper files are included in the project.

```bash
./mvnw clean package
```

--------------------------------

### Compile Application in Development Mode

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Use the Maven wrapper to compile the application source code. This command is typically used during development to build the project.

```bash
./mvnw compile
```

--------------------------------

### Get Countries by Name

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Searches for countries by name, supporting both substring and exact matches. Response fields can be filtered.

```APIDOC
## GET /v4/name/{name}

### Description
Searches countries by name, supporting both substring and exact matches. Allows filtering of response fields.

### Method
GET

### Endpoint
/v4/name/{name}

#### Path Parameters
- **name** (string) - Required - Country name (common or official)

#### Query Parameters
- **fullText** (boolean) - Optional - If true, searches for exact match; if false, substring match. Defaults to `false`.
- **fields** (string) - Optional - Field names for response filtering

### Response
#### Success Response (200)
- Returns an array of countries matching the name.

#### Error Responses
- **404 Not Found**: If no countries match the name.
- **500 Internal Server Error**: On processing exceptions.

### Behavior
- `fullText=false` (default): Substring search across common name, official name, and alternative spellings.
- `fullText=true`: Exact match against common or official name only.

### Example Requests
```
GET /v4/name/France
GET /v4/name/eesti?fullText=true
GET /v4/name/united?fields=name,region,languages
```
```

--------------------------------

### Run Tests with Maven

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Execute all project tests using the Maven test command. This verifies the functionality of the application.

```bash
./mvnw test
```

--------------------------------

### Get independent or non-independent countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Endpoint to retrieve countries based on their independence status. Can be combined with field filtering.

```HTTP
/v3.1/independent?status=true
```

```HTTP
?status=true&fields=languages,capital
```

--------------------------------

### Get All Countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/README.md

Retrieve all countries. You must specify the fields you need (up to 10) to avoid a 'bad request' response.

```html
https://restcountries.com/v3.1/all
```

--------------------------------

### Running Application with Custom Port

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Demonstrates how to override the default server port (8080) when running the application JAR.

```bash
java -jar app.jar -Dmicronaut.server.port=8081
```

--------------------------------

### Get Countries by Currency

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Searches for countries based on a provided currency code or name. Allows filtering of response fields.

```APIDOC
## GET /v4/currency/{currency}

### Description
Searches countries by currency code or name. Allows filtering of response fields.

### Method
GET

### Endpoint
/v4/currency/{currency}

#### Path Parameters
- **currency** (string) - Required - Currency code (e.g., "USD") or currency name

#### Query Parameters
- **fields** (string) - Optional - Field names for filtering response

### Response
#### Success Response (200)
- Returns an array of countries matching the currency.

#### Error Responses
- **400 Bad Request**: If the currency parameter is empty.
- **404 Not Found**: If no countries use the specified currency.
- **500 Internal Server Error**: On processing exceptions.

### Example Requests
```
GET /v4/currency/EUR
GET /v4/currency/bitcoin?fields=name,currencies
```
```

--------------------------------

### Configure Host via Command-Line Argument

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Set the server host address using the --micronaut.server.host argument. This allows binding the application to a specific network interface.

```bash
java -jar app.jar --micronaut.server.host=127.0.0.1
```

--------------------------------

### Get Independent Countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Retrieve a list of all independent countries. The `status` query parameter can be used to filter by independence status.

```APIDOC
## GET /v3.1/independent

### Description
Retrieve a list of all independent countries. The `status` query parameter can be used to filter by independence status.

### Method
GET

### Endpoint
/v3.1/independent

### Parameters
#### Query Parameters
- **status** (boolean) - Required - Set to `true` to get independent countries.

#### Query Parameters (Optional with fields filter)
- **fields** (string) - Optional - Comma-separated list of fields to include in the response (e.g., `languages,capital`).

### Response
#### Success Response (200)
- **name** (object) - Country's name details.

### Response Example
{
  "example": "[{\"name\": {\"common\": \"Germany\", \"official\": \"Federal Republic of Germany\"}}]"
```

--------------------------------

### Get Independent Countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/README.md

Retrieve all independent countries. The 'status' parameter defaults to true if not specified. Can be combined with the 'fields' filter.

```html
https://restcountries.com/v3.1/independent?status=true
```

```html
https://restcountries.com/v3.1/independent?status=true&fields=languages,capital
```

--------------------------------

### Cleaning and Packaging Maven Project

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Command to clean the project build artifacts and package it, useful for resolving classpath issues.

```bash
mvn clean package
```

--------------------------------

### Retrieve All Countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Get an unmodifiable set of all countries currently loaded in the in-memory cache. This method is safe to call after the service has been initialized.

```java
Set<Country> allCountries = CountryServiceV4.getInstance().getAll();
for (Country country : allCountries) {
  System.out.println(country.getName().getCommon());
}
```

--------------------------------

### V4 Endpoints (Equivalent to V3.1)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

All V3.1 endpoints are available in V4 by replacing the path prefix '/v3.1/' with '/v4/'. The behavior and parameters remain the same.

```APIDOC
## GET /v4/all

### Description
Retrieves all countries. Supports filtering by fields.

### Method
GET

### Endpoint
/v4/all

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```
GET /v4/all?fields=name,capital
```

## GET /v4/name/{name}

### Description
Searches for countries by their common or official name.

### Method
GET

### Endpoint
/v4/name/{name}

### Path Parameters
- **name** (string) - Required - The name of the country to search for.

### Request Example
```
GET /v4/name/Germany
```

## GET /v4/alpha/{alphaCode}

### Description
Retrieves country information using its Alpha code (2 or 3 letters).

### Method
GET

### Endpoint
/v4/alpha/{alphaCode}

### Path Parameters
- **alphaCode** (string) - Required - The Alpha-2 or Alpha-3 code of the country.

### Request Example
```
GET /v4/alpha/CO
```

## GET /v4/currency/{currencyCode}

### Description
Finds countries that use a specific currency.

### Method
GET

### Endpoint
/v4/currency/{currencyCode}

### Path Parameters
- **currencyCode** (string) - Required - The ISO 4217 currency code.

### Request Example
```
GET /v4/currency/USD
```

## GET /v4/capital/{capitalName}

### Description
Searches for countries by their capital city name.

### Method
GET

### Endpoint
/v4/capital/{capitalName}

### Path Parameters
- **capitalName** (string) - Required - The name of the capital city.

### Request Example
```
GET /v4/capital/Berlin
```

## GET /v4/region/{region}

### Description
Retrieves countries belonging to a specific region.

### Method
GET

### Endpoint
/v4/region/{region}

### Path Parameters
- **region** (string) - Required - The name of the region (e.g., Europe, Asia).

### Request Example
```
GET /v4/region/Europe
```

## GET /v4/subregion/{subregion}

### Description
Retrieves countries belonging to a specific subregion.

### Method
GET

### Endpoint
/v4/subregion/{subregion}

### Path Parameters
- **subregion** (string) - Required - The name of the subregion (e.g., Northern Europe).

### Request Example
```
GET /v4/subregion/Northern Europe
```

## GET /v4/lang/{languageName}

### Description
Finds countries where a specific language is spoken.

### Method
GET

### Endpoint
/v4/lang/{languageName}

### Path Parameters
- **languageName** (string) - Required - The name of the language.

### Request Example
```
GET /v4/lang/english
```

## GET /v4/demonym/{demonym}

### Description
Searches for countries based on their demonym (e.g., German, French).

### Method
GET

### Endpoint
/v4/demonym/{demonym}

### Path Parameters
- **demonym** (string) - Required - The demonym of the country.

### Request Example
```
GET /v4/demonym/german
```

## GET /v4/translation/{languageName}

### Description
Translates a country name into a specified language.

### Method
GET

### Endpoint
/v4/translation/{languageName}

### Path Parameters
- **languageName** (string) - Required - The target language for the translation (e.g., deutschland for German).

### Request Example
```
GET /v4/translation/deutschland
```

## GET /v4/independent

### Description
Filters countries based on their independence status.

### Method
GET

### Endpoint
/v4/independent

### Query Parameters
- **status** (boolean) - Required - `true` to get independent countries, `false` for dependent territories.

### Request Example
```
GET /v4/independent?status=true
```
```

--------------------------------

### Get Country by Name

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/src/main/resources/static/index.html

Search for a country by its common or official name. The `fullText` query parameter can be used to perform an exact match search.

```APIDOC
## GET /v3.1/name/{name}

### Description
Search for a country by its common or official name. The `fullText` query parameter can be used to perform an exact match search.

### Method
GET

### Endpoint
/v3.1/name/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The common or official name of the country to search for.

#### Query Parameters
- **fullText** (boolean) - Optional - If set to `true`, performs an exact match search for the country's full name.

### Response
#### Success Response (200)
- **name** (object) - Country's name details.

### Response Example
{
  "example": "{\"name\": {\"common\": \"Peru\", \"official\": \"Oriental Republic of Peru\"}}"
```

--------------------------------

### Run Application Jar

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Execute the application JAR file after building it. This command is typically used after a successful Maven package build.

```bash
java -jar target/restcountries-2025.04.20.jar
```

--------------------------------

### Get Countries by Sovereign State

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryControllerV4.md

Retrieves territories and dependencies associated with a given sovereign state, identified by its CCA3 code. Field filtering is supported.

```APIDOC
## GET /v4/sovereignstate/{cca3}

### Description
Searches for countries by sovereign state, applicable to territories and dependencies. Requires the CCA3 code of the governing sovereign state and supports field filtering.

### Method
GET

### Endpoint
/v4/sovereignstate/{cca3}

### Parameters
#### Path Parameters
- **cca3** (string) - Required - CCA3 code of the governing sovereign state (exactly 3 characters)

#### Query Parameters
- **fields** (string) - Optional - Field names for filtering

### Request Example
```
GET /v4/sovereignstate/GBR
GET /v4/sovereignstate/DNK?fields=name,capital,sovereignState
```

### Response
#### Success Response (200 OK)
- Returns an array of territories under the specified sovereign state.
```json
[
  {
    "name": {
      "common": "Greenland",
      "official": "Kalaallit Nunaat"
    },
    "capital": ["Nuuk"],
    "sovereignState": "DNK"
  },
  {
    "name": {
      "common": "Faroe Islands",
      "official": "Faroe Islands"
    },
    "capital": ["Tórshavn"],
    "sovereignState": "DNK"
  }
]
```

#### Error Response
- **400 Bad Request**: If cca3 is not exactly 3 characters.
- **404 Not Found**: If no territories match the sovereign state.
- **500 Internal Server Error**: On processing exception.
```

--------------------------------

### getInstance()

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Returns the singleton instance of CountryServiceV4. This method is used to access the service, which loads all countries into memory on its first call.

```APIDOC
## getInstance()

### Description
Returns the singleton instance of `CountryServiceV4`. This is the primary way to access the service, which caches all country data in memory upon first instantiation.

### Method
`public static CountryServiceV4 getInstance()`

### Return Type
`CountryServiceV4` - The singleton instance of the country service.

### Behavior
- The first call initializes the service and loads country data from `countriesV4.json`.
- Subsequent calls return the existing cached instance.
- The method is thread-safe.

### Example Usage
```java
CountryServiceV4 service = CountryServiceV4.getInstance();
Set<Country> allCountries = service.getAll();
```
```

--------------------------------

### GET /v3.1/currency/{currency}

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Finds countries that use a specific currency, identified by its code or name. The `fields` parameter allows for selective data retrieval.

```APIDOC
## GET /v3.1/currency/{currency}

### Description
Search countries by currency code or name.

### Method
GET

### Endpoint
/v3.1/currency/{currency}

### Parameters
#### Path Parameters
- **currency** (string) - Required - Currency code or name to search for.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated field names to include in the response.

### Response
#### Success Response (200)
- Array of Country objects using the specified currency

#### Response Example
(Array of Country objects, similar to /all endpoint, filtered by currency)
```

--------------------------------

### Configure Server Host

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Set the server host in `application.yml` to change the default host from `localhost`. This allows the server to listen on all available network interfaces.

```yaml
micronaut:
  server:
    host: 0.0.0.0
```

--------------------------------

### V4 HTTP Controller Reference

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/README.md

Documentation for the V4 HTTP controller, including 14 public methods, V4-specific changes, and parameter validation rules.

```APIDOC
## CountryControllerV4

### Description
Documentation for the V4 HTTP controller, including 14 public methods (includes sovereignstate endpoint), identical signatures to v3.1 with v4 data structure returns, V4-specific changes and new endpoint documentation, and parameter validation rules.

### Methods
- 14 public methods (includes sovereignstate endpoint)
- Identical signatures to v3.1 with v4 data structure returns
- V4-specific changes and new endpoint documentation
- Parameter validation rules
```

--------------------------------

### Java Country Object Serialization

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Example of a Java class annotated with @Serdeable.Serializable for JSON serialization. Null fields are omitted by default, and all public getters are serialized.

```java
@Serdeable.Serializable
public class Country extends BaseCountryCore {
    private Name name;
    private List<Currency> currencies;
    // ...
}
```

--------------------------------

### Configure Logging Levels in application.yml

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Sets logging levels for different packages in the application.yml file. Use DEBUG for com.restcountries, INFO for io.micronaut, and INFO for the root logger.

```yaml
logger:
  levels:
    com.restcountries: DEBUG
    io.micronaut: INFO
    root: INFO
```

--------------------------------

### V4 Server Routes

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Preview V4 API endpoints for retrieving country data, including new endpoints like sovereign state lookup.

```text
GET /v4/all
GET /v4/alpha/{code}
GET /v4/alpha?codes=...
GET /v4/name/{name}
GET /v4/capital/{capital}
GET /v4/region/{region}
GET /v4/subregion/{subregion}
GET /v4/currency/{currency}
GET /v4/lang/{language}
GET /v4/demonym/{demonym}
GET /v4/translation/{translation}
GET /v4/sovereignstate/{cca3}
GET /v4/independent
```

--------------------------------

### Configure Server Port

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/configuration.md

Set the server port in `application.yml` to override the default port 8080. This configuration is applied during application startup.

```yaml
micronaut:
  server:
    port: 8080
```

--------------------------------

### GET /v4/sovereignstate/{cca3}

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

This V4-only endpoint allows searching for countries governed by a specific sovereign state, applicable to territories and dependencies. It requires the CCA3 code of the sovereign state.

```APIDOC
## GET /v4/sovereignstate/{cca3}

### Description
Search countries by sovereign state (applicable to territories and dependencies).

### Method
GET

### Endpoint
/v4/sovereignstate/{cca3}

### Path Parameters
- **cca3** (string) - Required - CCA3 code of the sovereign state (exactly 3 characters).

### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Response
- **Array of Country objects** governed by the specified sovereign state.

### Status Codes
- **200 OK** on match
- **404 Not Found** if no matches
- **400 Bad Request** if cca3 is not exactly 3 characters

### Request Example
```
GET /v4/sovereignstate/GBR
```
```

--------------------------------

### Private Constructor

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

The private constructor ensures the singleton pattern, initializing the service once per JVM.

```java
private CountryServiceV4()
```

--------------------------------

### Initialize Countries

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Loads countries from a JSON resource file during the first instantiation of the service. It uses Gson for deserialization and populates an in-memory set.

```java
private void initialize()
```

--------------------------------

### GET /v3.1/capital/{capital}

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Searches for countries based on their capital city name. This performs a substring match on the capital city. The `fields` parameter can be used to limit the returned data.

```APIDOC
## GET /v3.1/capital/{capital}

### Description
Search countries by capital city name.

### Method
GET

### Endpoint
/v3.1/capital/{capital}

### Parameters
#### Path Parameters
- **capital** (string) - Required - Capital city name to search for (substring match).

#### Query Parameters
- **fields** (string) - Optional - Comma-separated field names to include in the response.

### Response
#### Success Response (200)
- Array of Country objects with matching capital

#### Response Example
(Array of Country objects, similar to /all endpoint, filtered by capital)
```

--------------------------------

### Search Countries by Currency

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Searches for countries using a currency code or name. Matching is case-insensitive and performs a substring match on the currency name.

```java
Set<Country> euroCountries = service.getByCurrency("EUR");
// Returns all countries with EUR in currencies list

Set<Country> dollarCountries = service.getByCurrency("dollar");
// Returns countries with "dollar" in currency name
```

--------------------------------

### V3 Server Routes

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Legacy V3 API endpoints for retrieving country data.

```text
GET /v3/all
GET /v3/alpha/{code}
... (other v3 endpoints)
```

--------------------------------

### getByCapital(String capital)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Searches for countries by capital city name using case-insensitive substring matching.

```APIDOC
## getByCapital(String capital)

### Description
Searches for countries by capital city name using case-insensitive substring matching.

### Method
GET (Assumed based on search operation)

### Endpoint
/countries/capital/{capital}

### Parameters
#### Path Parameters
- **capital** (String) - Yes - Capital city name (substring match)

### Request Example
```json
{
  "capital": "London"
}
```

### Response
#### Success Response (200)
- **Set<Country>** - Zero or more countries with matching capital

#### Response Example
```json
[
  {
    "capital": "London",
    "name": "United Kingdom"
  }
]
```
```

--------------------------------

### V2 Server Routes

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/Application.md

Legacy V2 API endpoints for retrieving country data.

```text
GET /v2/all
GET /v2/alpha/{code}
GET /v2/alpha?codes=...
... (other v2 endpoints)
```

--------------------------------

### Search Countries by Name (Substring and Exact Match)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Search for countries by name. Use `isFullText=false` for a case-insensitive substring search across common, official, and alternative names. Use `isFullText=true` for an exact match against common or official names only. Diacritical marks are normalized.

```java
// Substring search
Set<Country> results = service.getByName("united", false);
// Returns: United States, United Kingdom, United Arab Emirates, etc.

// Exact match
Set<Country> exact = service.getByName("France", true);
// Returns: France (exact match)
```

--------------------------------

### getByCodeList(String codeList)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/api-reference/CountryServiceV4.md

Searches for multiple countries by a comma-separated list of country codes. Results are a union of all matches.

```APIDOC
## getByCodeList(String codeList)

### Description
Searches for multiple countries by a comma-separated list of country codes. Results are a union of all matches.

### Method
GET (Assumed based on search operation)

### Endpoint
/countries/codes/{codeList}

### Parameters
#### Path Parameters
- **codeList** (String) - Yes - Comma-separated country codes (e.g., "CO,PE,VE")

### Request Example
```json
{
  "codeList": "CO,PE,VE"
}
```

### Response
#### Success Response (200)
- **Set<Country>** - Zero or more countries matching any code in the list

#### Response Example
```json
[
  {
    "alpha3Code": "COL",
    "name": "Colombia"
  },
  {
    "alpha3Code": "PER",
    "name": "Peru"
  }
]
```
```

--------------------------------

### Search by Currency

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/README.md

Find countries based on their currency code or currency name.

```html
https://restcountries.com/v3.1/currency/{currency}
```

```html
https://restcountries.com/v3.1/currency/cop
```

--------------------------------

### GET /v3.1/alpha/?codes={code},{code},...

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Fetches multiple countries by providing a comma-separated list of alpha codes (cca2, cca3, ccn3, or cioc). The `fields` parameter can be used to filter the response data.

```APIDOC
## GET /v3.1/alpha/?codes={code},{code},...

### Description
Search multiple countries by a comma-separated list of alpha codes.

### Method
GET

### Endpoint
/v3.1/alpha/

### Parameters
#### Query Parameters
- **codes** (string) - Required - Comma-separated list of country codes (cca2, cca3, ccn3, or cioc).
- **fields** (string) - Optional - Comma-separated field names to include in the response.

### Response
#### Success Response (200)
- Array of Country objects for matched codes

#### Response Example
```json
[
  {
    "name": {"common": "Colombia", "official": "Republic of Colombia"},
    "cca2": "CO",
    "cca3": "COL"
  },
  {
    "name": {"common": "Norway", "official": "Kingdom of Norway"},
    "cca2": "NO",
    "cca3": "NOR"
  }
]
```
```

--------------------------------

### GET /v3.1/alpha/{code}

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/endpoints.md

Retrieves a single country using its alpha code. Accepts 2-letter (cca2), 3-letter (cca3), or numeric (ccn3, cioc) codes. The `fields` parameter can be used to specify which data to return.

```APIDOC
## GET /v3.1/alpha/{code}

### Description
Search a single country by alpha code (2-letter, 3-letter, or numeric).

### Method
GET

### Endpoint
/v3.1/alpha/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - cca2, ccn3, cca3, or cioc code (2-3 characters).

#### Query Parameters
- **fields** (string) - Optional - Comma-separated field names to include in the response.

### Response
#### Success Response (200)
- Single Country object or empty if not found

#### Response Example
(Country object structure, similar to /all endpoint, but for a single country)
```

--------------------------------

### Country Type Definition (v3.1)

Source: https://gitlab.com/restcountries/restcountries/-/blob/master/_autodocs/types.md

Defines the complete data structure for a country in the v3.1 API. It extends BaseCountry and includes specific fields like flags, coat of arms, start of week, and capital information.

```java
package com.restcountries.domain.v3.v31;

public class Country extends BaseCountry {
  private Flag flags;                    // Flag and coat of arms
  private Flag coatOfArms;               // Coat of arms
  private String startOfWeek;            // Day week starts (e.g., "monday")
  private CapitalInformation capitalInfo;// Capital additional data
  private Map<String, String> postalCode;// Postal code info
}
```