Développer une API Rest en Clojure : partie 2

Matthieu SAUBOUA-BENELUZ 25 oct. 2017

Maintenant que notre projet est prêt, nous pouvons commencer les développements de notre API REST. Ici nous verrons pas à pas comment mettre vos données à disposition via des endpoints REST avec Clojure.

Structure de l’application

Pas de description détaillée de la structure ici mais quelques explications sur mon choix d’implémentation. Vous remarquerez en parcourant cet article que j’ai choisi une architecture en couches pour mon application : controleur, services, dao, model …

J’attire votre attention sur les DAO, résultat de mes habitudes de développeur Java. DAO signifiant Data Access Object, le principe n’a pas vraiment sa place en Clojure idiomatique car il n’utilise pas vraiment d’objets ou de classes. Ceci dit, cela vous montre que Clojure ne vous contraint pas à adopter une structure en particulier. L’important reste d’organiser vos namespaces par cas d’utilisation, pour plus de clarté.

Attention : même si Clojure est assez flexible, il ne vous permet pas de faire des références circulaires dans vos namespaces. Il faut donc bien séparer les responsabilités dans votre code. Sinon cela pourrait vous poser de gros problèmes, comme dans beaucoup d’autres langages d’ailleurs.

Ajouter le handler

Par convention, il faut définir une variable pour ring qui répertorie toutes les routes. Appelée depuis le project.clj, celle-ci constitue le point d’entrée de l’application. Vous pouvez déclarer vos routes directement dans ce fichier si vous le souhaitez, mais dans notre cas nous procéderons comme suit :

src/clojure_rest/handler.clj

(ns clojure-rest.handler
  (:require [compojure.core :refer :all]
            [compojure.handler :as handler]
            [compojure.route :as route]
            [clojure-rest.config.routes :as config-routes]))

(def app config-routes/app-routes)

Définir le modèle

L’ORM choisi pour ce projet est Korma. Pour les habitués d’Hibernate, il faut donc déclarer la table et ses différentes contraintes. Pas de déclaration de classe en Clojure, c’est la macro defentity de Korma qui vous permet de le faire. Les macros sont une fonctionnalité puissante de Clojure, pour en savoir plus rendez-vous sur la documentation officielle. Ici nous ajoutons la table associée, la clé primaire, ainsi que les champs qui seront ramenés par défaut par un select.

(ns clojure-rest.model.document
  (:use [korma.core :only [defentity table entity-fields pk]])
  (:require [clojure.tools.logging :as log]
            [schema.core :as schema]))

; -- Korma configuration
(defentity document
  (table :document) ; Associated table
  (pk :id_document) ; primary key
  (entity-fields :id_document :title :description))

; -- Validation schema for complete document
(def document-schema
  {:id_document schema/Str
   :title schema/Str
   :description schema/Str})

; -- Validation for input rest document
(def document-schema-rest-in
 {:title schema/Str
  :description schema/Str})

En Clojure, on fonctionne surtout avec des maps pour visualiser notre modèle, il n’y pas de classes à proprement parler, même si on peut simuler ce type de comportement (Notamment avec la macro defrecord ou de l'interop Java). La bibliothèque schema nous permet d’imposer des types dans notre map et de vérifier si une map en entrée respecte ces contraintes. C’est en quelque sorte un mécanisme de Bean Validation.

Deux modèles sont définis : document_schema pour un document complet, et document_schema_rest_in que nous utiliserons pour les documents envoyés par l’utilisateur, pour la création ou la mise à jour. Ces schémas sont validables via la méthode schema/validate, ou directement dans la déclaration des routes.

Implémenter les routes

Nous avons défini le handler et notre modèle, il faut maintenant implémenter nos routes. Grâce à la bibliothèque compojure-api, définir les routes et leur documentation Swagger est très simple. Commençons d’abord par configurer Swagger.

Configurer Swagger

Swagger donne accès à une interface graphique qui liste vos endpoints et vous permet de requêter facilement pour vos tests, ou pour documenter votre API auprès des futurs utilisateurs. Rendez-vous à cette adresse pour voir une démonstration plus explicite. En Clojure, la configuration se fait sous forme de map :

src/clojure_rest/config/swagger.clj

(ns clojure-rest.config.swagger)

(def swagger-routes
  {:swagger
   {:ui "/api-docs"
    :spec "/swagger.json"
    :data {:info {:title "Simple Clojure API"
                  :description "Example Clojure api for Ippon Blog Article"}
           :tags [{:name "api-documents", :description "Api document endpoints"}]}}})

Ici je mentionne l’url “/api-docs” qui nous permettra d’accéder à l’interface ainsi que d’autres descriptifs que nous verrons à l’affichage (Voir le dépôt github pour un aperçu). Reste maintenant à implémenter nos routes.

Ajouter les routes et leur documentation

Grâce à compojure-api, la déclaration des routes et leur documentation Swagger se fait au même endroit. Importons les dépendances nécessaires et définissons nos routes documents et leur contexte :