Countries

The following API routes are available under the countries prefix. These routes are cached with public headers and a max age of 3600 seconds .

List of API end-points prefix countries

1. GET: /countries/_ping
2. GET: /countries

Middleware

• Cache Headers: All routes under this prefix have caching headers set to public with a max_age of 3600 seconds.

Routes Prefix /countries

1. Health Check

• GET /countries/_ping
  • Controller: PingController
  • Description: Checks if the API is alive and responsive.
  • Request:
    • Method: GET
    • URL: https://base_url/ecom/v1/countries/_ping
    • Parameters: None
  • Response:

    {
    data:
    {
      "status": "ok"
    }
    }
    

2. GET: ../countries

• Namespace and Imports: The controller is part of the App\Http\Controllers\Api namespace
• Service Dependencies: CountryService Used to fetch the list of countries. It interacts with the underlying data source to retrieve country information.
• Description: This API endpoint returns a list of all countries with their details, including address formatting and validation rules.
• Constructor

  public function __construct(CountryService $countryService)
  

• Request:
  • Method: GET
  • URL: https://base_url/ecom/v1/countries
  • Parameters: None
• Response:
  • Status: 200 OK
  • headers:
    • Content-Type: application/json
    • Cache-Control: public, max-age=3600
  • Response Body: The response is an array of country objects. Each country object contains the following fields:

       [
        {
        "id": "string",
        "name": "string",
        "iso3166_2": "string",
        "iso3166_3": "string",
        "currency": "string",
        "address_format": [
            "string"
        ],
        "rules": {
            "string": [
                "string"
            ]
           }
        }
      ]
    

    • Field Description
      • id: The unique identifier of the country.
      • name: The name of the country.
      • iso3166_2: The ISO 3166-2 code for the country.
      • iso3166_3: The ISO 3166-3 code for the country.
      • currency: The currency used in the country.
      • address_format: An array representing the format of the address fields. Fields are renamed according to the mapping provided (house becomes line_1, a_road becomes line_2, etc.).
      • rules: An associative array where keys are address field names and values are validation rules.
  • Example Response:

    // Example:- https://base_url/ecom/v1/countries
    "data": [
       {
           "id": x,
           "name": "United Kingdom",
           "iso3166_2": "GB",
           "iso3166_3": "GBR",
           "currency": "GBR",
           "address_format": [
               "line_1",
               "line_2",
               "line_3",
               "town",
               "county",
               "postcode",
               "country"
           ],
           "rules": {
               "line_1": [
                   "required"
               ],
               "town": [
                   "required"
               ],
               "county": [
                   "max:32"
               ]
           }
       },
    

• Error Response: Possible Error Responses
  • 400 Bad Request: If the request is malformed or contains invalid parameters.
  • 500 Internal Server Error: If there is an issue with the server or service.

CountryResource Class

Overview

The CountryResource class is a Laravel JSON resource used to transform a Country model instance into a structured array format suitable for API responses. This class handles the formatting and localization of address fields and validation rules based on the country’s specific configuration.

Methods

toArray($request): array

• Description: Transforms the Country model instance into an array for API responses. It formats the address fields and applies localization and validation rules based on the country configuration.
• Parameters:
  • Request $request: The HTTP request object.
• Returns: An associative array containing the country’s details and configuration.
• Functionality:
  • Uses a match expression to translate specific address line names:
    • house becomes line_1
    • a_road becomes line_2
    • b_road becomes line_3
    • Other names are returned unchanged.

The toArray method will produce:

        {
           "id": "x",
           "name": "United States",
           "iso3166_2": "US",
           "iso3166_3": "USA",
           "currency": "USD",
           "address_format": [
                "line_1",
                "line_2",
                "line_3",
                "city",
                "state",
                 "postal_code"
           ],
        "rules": {
             "line_1": ["required", "string"],
              "line_2": ["nullable", "string"],
             "line_3": ["nullable", "string"],
             "city": ["required", "string"],
             "state": ["required", "string"],
             "postal_code": ["required", "string"]
        }
        }

CountryService Interface

The CountryService interface defines the contract for services that manage country-related data. It includes methods for retrieving collections of countries and individual country details based on ISO codes or country IDs.

Methods

• get()

  public function get(): Collection;
  

  • Description: Retrieves a collection of all countries.
  • Returns: Collection - A collection of country entities.
• getByIsoCodes(array $codes)

    public function getByIsoCodes(array $codes);
  

  • Description: Retrieves country details based on the provided ISO codes.
  • Parameters:
    • array $codes - An array of ISO country codes.
  • Returns: mixed - The country details corresponding to the provided ISO codes. The exact type depends on the implementation.
• getCountryById(int $countryId)

    public function getCountryById(int $countryId);
  

  • Description details of a country based on the provided country ID.
  • Parameters:
    • int $countryId - The ID of the country to retrieve.
  • Returns: mixed - The country details corresponding to the provided country ID. The exact type depends on the implementation.