Développement d’API avec Ktor

1. Qu’est-ce que Ktor ?

Ktor est un framework de développement écrit entièrement en Kotlin. Il est utilisé pour développer des applications web ou clientes. Par exemple, il peut être employé tant pour le développement de la composante « backend » d’une application que pour l’établissement de la connectivité avec le serveur depuis une application mobile écrite en Kotlin.

L’objectif du framework Ktor est de fournir un cadre unique pour le développement de l’ensemble des composantes d’une application, qu’il s’agisse du côté client ou serveur.

Pour optimiser ses performances lors de l’exécution de multiples requêtes HTTP concurrentes, Ktor a recours au modèle de programmation asynchrone qui repose sur les coroutines. Ce modèle lui permet d’exécuter les opérations de manière non bloquante et de pouvoir gérer de nombreuses connexions avec un nombre réduit de threads système.

2. Comparaison avec le framework Spring

Spring est un framework de développement extrêmement populaire, écrit en Java. Il s’agit d’un framework complet, fondé sur les principes d’injection de dépendances et d’inversion de contrôle. Il est souvent employé conjointement avec le framework SpringBoot afin d’accélérer le développement d’applications web.

Il est parfaitement possible d’utiliser Spring et/ou SpringBoot en Kotlin. Comme évoqué dans les premiers chapitres, Kotlin est un langage de programmation compatible à 100 % avec Java et tous les langages compilés en ByteCode de la JVM. Toutefois, l’emploi de Spring et/ou SpringBoot en Kotlin ne permet pas de tirer pleinement parti de tous les avantages et de toute la puissance du langage.

1. Écrire une API REST

import io.ktor.server.application.Application 
import io.ktor.server.routing.delete 
import io.ktor.server.routing.get 
import io.ktor.server.routing.post 
import io.ktor.server.routing.put 
import io.ktor.server.routing.routing 
 
fun Application.module() { 
    routing { 
        get("/teams") { 
        } 
 
        get("/teams/{team_id}") { 
        } 
 
        post("/teams") { 
        } 
 
        put("/teams/{team_id}") { 
        } 
 
        delete("/teams/{team_id}") { 
        } 
 
        get("/teams/{team_id}/players") { 
        } 
 
        post("/teams/{team_id}/players") { 
        } 
 
        put("/teams/{team_id}/players/{player_id}") { 
        } 
 
        delete("/teams/{team_id}/players/{player_id}") { 
        } 
    } 
} 

1. Authentification basique

L’authentification (AuthN) est la première brique à mettre en place pour sécuriser son API. Elle permet de valider l’identité de l’utilisateur de l’API. Il est important de ne pas confondre Authn avec l’autorisation (AuthZ) qui permet de déterminer les actions qu’un utilisateur déjà authentifié pourra réaliser dans l’application.

Le moyen le plus simple pour implémenter l’authentification est de transmettre les informations d’identification (par exemple, le nom d’utilisateur et son mot de passe) à chaque requête HTTP. Cette procédure est réalisée grâce à la structure d’authentification du protocole HTTP appelée « l’authentification basique » (basic authentication). Cette authentification se base sur l’en-tête Authorization du protocole HTTP.

Pour authentifier l’utilisateur, le client HTTP génère une chaîne de caractères contenant les informations d’identification de l’utilisateur. Le format de cette chaîne doit être connu par le client et le serveur. Généralement, le format suivant est utilisé :

username:password 

L’en-tête Authorization est créé en encodant la chaîne de caractères avec l’algorithme « Base64 ». Ensuite, pour chaque requête nécessitant une authentification, la valeur encodée est placée dans l’en-tête Authorization comme suit :

Authorization : Basic dXNlcm5hbWU6cGFzc3dvcmQ= 

Une fois la requête reçue par le serveur, ce dernier décode la valeur contenant les informations d’identification en utilisant le même algorithme « Base64 ». Il procède ensuite à la validation de l’identité de l’utilisateur avant de répondre à la requête. Si les informations d’identification ne sont pas correctes, une réponse HTTP avec le statut 401 est généralement renvoyée.

Pour intégrer l’authentification basique à une application Ktor, il est nécessaire d’ajouter en premier lieu le plugin Authentication et sa dépendance io.ktor:ktor-server-auth :

implementation("io.ktor:ktor-server-auth:2.3.5") 

<dependency> 
    <groupId>io.ktor</groupId> 
    <artifactId>ktor-server-auth</artifactId> 
    <version>2.3.5</version> 
</dependency> 

Une fois la dépendance ajoutée, il est nécessaire d’installer et de configurer le plugin :

install(Authentication) { 
        basic { 
            validate { credentials -> 
            } 
        } 
    } 

La méthode validate est appelée par le plugin Ktor à chaque requête HTTP à authentifier. Son argument est une lambda prenant un paramètre de type UserPasswordCredential et renvoyant un objet nullable de type Principal. Le paramètre UserPasswordCredential contient le nom de l’utilisateur ainsi que son mot de passe, tous deux décodés. Il est important de noter que Ktor utilise, par défaut, le format username:password pour transmettre...

1. Documentation OpenAPI

OpenAPI est un standard utilisé pour documenter les API d’une application. Il définit des règles et des formats de documentation indépendants des frameworks utilisés pour développer l’application. Cette norme permet de définir clairement le contrat de l’API et de développer le serveur et le client de manière indépendante. De plus, il existe des outils permettant de générer du code pour le client et le serveur à partir d’une spécification utilisant le standard OpenAPI.

Le framework Ktor ne permet pas de générer automatiquement une spécification OpenAPI depuis la définition des routes. Les développeurs sont donc contraints à respecter la recommandation qui conseille de définir la spécification OpenAPI de leurs API avant de commencer le développement de ces derniers. 

Une spécification OpenAPI peut être rédigée en format YAML ou en format JSON. Elle spécifie la version de l’API, la méthode d’authentification et les différentes routes exposées par l’API.

La première section de la documentation définit la version du standard OpenAPI et les informations générales sur l’application :

openapi: 3.0.0 
info: 
  version: 1.0.0 
  title: Teams application API 
  description: An API to manage teams and players 

L’exemple utilise la dernière version du standard disponible 3.0.0. Chaque nouvelle version du standard peut impacter le format du fichier de la documentation. L’exemple définit aussi une version 1.0.0. Cette version représente la version de l’API de l’application. Cette dernière peut être différente de la version de l’application. Généralement, cette version est incrémentée lors de l’ajout ou la suppression de routes. Il est recommandé de passer à une nouvelle version majeure lorsque des changements impactant la compatibilité avec la version antérieure sont introduits.

La deuxième section documente les informations globales sur l’API ainsi que des éléments réutilisables par les différentes routes. Parmi ces éléments figure la méthode d’authentification de l’API. L’exemple suivant illustre une spécification d’une API utilisant JWT comme méthode d’authentification :

 components: 
  securitySchemes: 
    BasicAuth: 
      type:...

1. Configuration de l’environnement de test

Le module de test de Ktor facilite l’écriture de tests unitaires pour les requêtes HTTP de l’application. Afin de l’utiliser, il est nécessaire d’avoir une configuration de projet comprenant un moteur d’exécution de tests unitaires : la bibliothèque JUnit de l’écosystème Java par exemple, ou la bibliothèque Kotest présentée dans la section sur l’écriture des tests en Kotlin du chapitre Présentation du langage Kotlin de cet ouvrage.

Une fois un moteur d’exécution de test unitaire intégré à la configuration du projet, le module de test des requêtes peut être ajouté grâce à la dépendance suivante :

testImplementation("io.ktor:ktor-server-test-host:2.3.5") 

<dependency> 
    <groupId>io.ktor</groupId> 
    <artifactId>ktor-server-test-host</artifactId> 
    <version>2.3.5</version> 
    <scope>test</scope> 
</dependency> 

2. Écriture du test

Pour la suite de cette section, nous allons écrire un test unitaire pour l’API REST suivante :

fun Application.teamManagementModule() { 
    val teams: MutableMap<Int, Team> = mutableMapOf() 
 
    routing { 
        post("/teams") { 
            val team = call.receive<Team>() 
            if (teams.containsKey(team.id)) { 
                call.respond(HttpStatusCode.Conflict) 
            } else { 
                teams[team.id] = team 
                call.respond(HttpStatusCode.OK, team.id) 
            } 
        } 
    } 
} 

L’API comprend une seule route HTTP de type « POST ». Cette route permet de récupérer un objet de type Team et de l’ajouter dans la « Map »...

1. Installation et configuration

Pour cette section, le choix du moteur utilisé se portera sur le moteur CIO, entièrement écrit en Kotlin. Il est nécessaire d’ajouter les deux dépendances suivantes :

implementation("io.ktor:ktor-client-core:2.3.5") 
implementation("io.ktor:ktor-client-cio:2.3.5") 

<dependency> 
    <groupId>io.ktor</groupId> 
    <artifactId>ktor-client-core</artifactId> 
    <version>2.3.5</version> 
</dependency> 
<dependency> 
    <groupId>io.ktor</groupId> 
    <artifactId>ktor-client-cio</artifactId> 
    <version>2.3.5</version> 
</dependency> 

Chaque client HTTP est représenté par une instance de la classe io.ktor.client.HttpClient. Cette instance est créée en spécifiant le moteur choisi comme suit :

import io.ktor.client.HttpClient 
import io.ktor.client.engine.cio.CIO 
 
val client = HttpClient(CIO) 

Si un seul moteur est présent dans les dépendances de l’application, il est possible de l’omettre lors de la création de l’instance :

import io.ktor.client.HttpClient 
 
val client = HttpClient() 

Dans ce cas, Ktor détecte et utilise automatiquement le moteur HTTP trouvé dans les dépendances.

2. Configuration d’un plugin

Le client HTTP de Ktor se base aussi sur le système de plugins. Il existe différents plugins...

1. Configurer le plugin WebSockets

Le plugin Ktor pour l’intégration des WebSockets nécessite la dépendance ktor-server-websockets :

implementation("io.ktor:ktor-server-websockets:2.3.5") 

<dependency> 
    <groupId>io.ktor</groupId> 
    <artifactId>ktor-server-websockets</artifactId> 
    <version>2.3.5</version> 
</dependency> 

Une fois la dépendance ajoutée, le plugin peut être installé, de la même façon que les autres plugins, en utilisant la méthode install :

import io.ktor.server.websocket.WebSockets 
 
install(WebSockets) 

Optionnellement, ce plugin permet de configurer les différents paramètres du protocole WebSockets, comme par exemple :

Ces propriétés sont configurables en passant une lambda à la méthode d’installation :

install(WebSockets) { 
    pingPeriod = Duration.of(5, ChronoUnit.SECONDS) 
    timeout = Duration.of(1, ChronoUnit.MINUTES) 
    masking = true 
} 

La configuration précédente demande à Ktor d’envoyer des messages de « ping »...

1. Logging

Le logging consiste à générer un journal d’événements produits par l’application. Ces événements peuvent être normaux. Ils ont dans ce cas un but informatif. Ils permettent de connaître les traitements et les opérations réalisés par l’application durant son fonctionnement nominal. Les événements peuvent également être anormaux. Ils permettent alors de conserver une trace des erreurs générées par l’application. L’ensemble de ces événements est utile pour déboguer une application et pour vérifier le processus des traitements exécutés. Généralement, à chaque événement sont associés un niveau de sévérité, un message et la date où l’événement s’est produit. Toutes ces données sont ensuite regroupées dans un seul fichier de journal (log) suivant un format prédéfini.

Dans l’écosystème de la JVM, plusieurs bibliothèques et frameworks sont disponibles pour la gestion des journaux de logs. Parmi les plus connus figurent Log4j et Logback. Toutefois, il est possible de découpler une application du framework de logging en utilisant la bibliothèque SLF4J. Grâce à cette librairie, il devient facile de passer d’un framework de logging à un autre sans avoir à modifier le code de l’application. Seule la configuration sera impactée par un tel changement.

Le framework Ktor utilise SLF4J comme librairie de logging quand l’application cible la JVM. Il est important de noter que SLF4J est simplement une couche d’abstraction. Il est donc nécessaire d’ajouter comme dépendance un des frameworks de logging.

Dans cette section, nous allons utiliser le framework Logback pour générer les journaux de logs de l’application.

Il est donc nécessaire d’ajouter la dépendance suivante :

runtimeOnly("ch.qos.logback:logback-classic:1.4.14") 

<dependency> 
    <groupId>ch.qos.logback</groupId> 
    <artifactId>logback-classic</artifactId> 
    <version>1.4.14</version> 
    <scope>runtime</scope> 
</dependency> 

Il est ensuite nécessaire d’ajouter un fichier de configuration. Ce fichier XML définit le format des événements de log générés par l’application :

    <appender name="STDOUT" class=
"ch.qos.logback.core.ConsoleAppender"> 
        <encoder> 
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] 
%-5level %logger{36} - %msg%n</pattern> 
        </encoder> 
    </appender> 

Tous les événements de logs respecteront le format %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n.

1. Déploiement sous forme d’un Fat-JAR

Un Fat-JAR est une archive JAR contenant l’application, sa configuration ainsi que toutes ses dépendances. Ce format permet d’avoir un seul fichier à transférer et à déployer sur un serveur. Le fichier JAR est exécutable à l’aide de la commande Java suivante :

java -jar path/to/fatjar.jar 

Ce mode de déploiement est utilisé pour sa simplicité. Il est néanmoins nécessaire de s’assurer que le serveur utilise la même version de Java installée pour pouvoir démarrer l’application.

gradle buildFatJar 

archivesName.set("new-fat-jar-name.jar") 

<plugins> 
    <plugin> 
            <groupId>org.apache.maven.plugins</groupId> 
            <artifactId>maven-assembly-plugin</artifactId> 
            <version>2.6</version> 
            <configuration> 
                <descriptorRefs> 
                    <descriptorRef>jar-with-dependencies</descriptorRef> 
                </descriptorRefs> 
                <finalName>my-ktor-application</finalName> 
                <appendAssemblyId>false</appendAssemblyId> 
                <archive> 
                    <manifest> 
                        <mainClass>io.ktor.server.cio.EngineMain</mainClass> 
                    </manifest> ...