Découvrons la plateforme REST Countries

Pour le moment, les pays affichés dans notre application sont directement déclarés dans le code avec AppData :

object AppData {
    val countries = listOf(
        Country(
            name = "France",
            fifaCode = "FRA",
            flag = "🇫🇷"
        ),
        Country(
            name = "Brésil",
            fifaCode = "BRA",
            flag = "🇧🇷"
        )
    )
}

Cette approche devient difficile à maintenir lorsque nous voulons afficher une liste complète de tous les pays. Au lieu d’écrire toutes ces données manuellement, nous allons les récupérer depuis Internet.

Nous allons chercher une plateforme qui possède déjà ces données et qui permet à d’autres applications de les récupérer via une API REST.

C'est quoi REST Countries

REST Countries est un service qui fournit différentes informations sur les pays, par exemple leur nom, leur capitale, leur population, etc.

Notre application n’a pas besoin de toutes les informations. Pour chaque pays, nous voulons uniquement récupérer son nom, son code FIFA et son drapeau.

Ces trois valeurs correspondent déjà aux propriétés de notre classe Country :

data class Country(
    val name: String,
    val fifaCode: String,
    val flag: String,
)

Comprendre un endpoint

Une API peut proposer plusieurs adresses correspondant à différentes ressources. Ces adresses sont appelées des endpoints.

Pour récupérer la liste des pays, nous utiliserons l’endpoint suivant :

GET https://api.restcountries.com/countries/v5

GET est une méthode HTTP utilisée pour demander des données à un serveur. REST Countries peut retourner beaucoup d’informations pour chaque pays. Nous pouvons utiliser le paramètre response_fields pour préciser les propriétés dont notre application a besoin : response_fields=names.common,codes.fifa,flag.emoji

Notre requête utilisera donc cette adresse :

https://api.restcountries.com/countries/v5?response_fields=names.common,codes.fifa,flag.emoji

Demander seulement les champs nécessaires permet de réduire la quantité de données téléchargées et de simplifier la réponse que nous devrons traiter.

Comprendre la réponse de l’API

Lorsque la requête réussit, REST Countries retourne une réponse au format JSON. JSON est un format textuel fréquemment utilisé pour échanger des données entre un serveur et une application. Voici une version simplifiée de la réponse que nous recevrons :

{
  "data": {
    "objects": [
      {
        "names": {
          "common": "Afghanistan"
        },
        "codes": {
          "fifa": "AFG"
        },
        "flag": {
          "emoji": "🇦🇫"
        },
        "meta": {
          "lastUpdatedTimestamp": 1783005246
        }
      },
      {
        "names": {
          "common": "Albania"
        },
        "codes": {
          "fifa": "ALB"
        },
        "flag": {
          "emoji": "🇦🇱"
        },
        "meta": {
          "lastUpdatedTimestamp": 1783005246
        }
      }
    ]
  }
}

La propriété data contient le résultat principal de la requête. À l’intérieur de data, la propriété objects contient la liste des pays :

data
└── objects
    ├── Afghanistan
    └── Albania

Chaque pays contient ensuite les propriétés qui nous intéressent :

names.common → Afghanistan codes.fifa → AFG flag.emoji → 🇦🇫

Dans une prochaine étape, nous créerons des classes Kotlin qui reproduisent cette structure.

Nous savons maintenant quel service utilisera l’application et quelle forme auront les données reçues. Dans la prochaine partie, nous allons créer un compte REST Countries et récupérer la clé d’API nécessaire pour envoyer notre première requête.