README.md

# Tutoriel REST - premier développement d'une ressource

Pour ce premier TP REST, nous allons voir les principaux éléments du développement d'une ressource :

  - POJO annoté
  - Objets de transfert (Data Transfer Object - DTO)
  - Gestion des représentations (JSON ou XML)
  - Gestion du cache (ETag)
  
## Mise en place de l'environnement

Le développement sera basé sur [`Jersey`](https://eclipse-ee4j.github.io/jersey/) qui fournit une implémentation de référence de JAX-RS. Vous trouverez dans la [documentation](https://eclipse-ee4j.github.io/jersey.github.io/documentation/latest3x/index.html) l'utilisation des annotation standards ainsi que les aspects spécifiques de la plate-forme.

Le développement avec Jersey implique l'utilisation de `Maven` pour la gestion des phases de développement. Maven va télécharger les librairies nécessaires depuis un dépôt extérieur. Il faut donc le configurer pour passer par le proxy quand vous êtes en salle de TP.

Dans le répertoire `~/.m2/` (a créer si nécessaire), créez le fichier 'settings.xml' avec le contenu suivant :

~~~xml
<settings>
  <proxies>
	<proxy>
  	  <id>ulille-proxy</id>
      <active>true</active>
	  <protocol>http</protocol>
	  <host>cache.univ-lille.fr</host>
	  <port>3128</port>
   	</proxy>
	<proxy>
	  <id>lille1-proxy-sec</id>
	  <active>true</active>
	  <protocol>https</protocol>
	  <host>cache.univ-lille.fr</host>
	  <port>3128</port>
	</proxy>
  </proxies>
</settings>
~~~

## Configuration de Maven
Le projet que vous avez récupéré contient le fichier de configuration `pom.xml`. Le projet est actuellement configuré pour utiliser java 11 :

~~~xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.8.1</version>
  <inherited>true</inherited>
  <configuration>
    <release>11</release>
  </configuration>
</plugin>
~~~

## Le code récupéré
L'arborescence de source contient les fichiers suivants :

~~~
src
├── main
│   └── java
│       └── fr
│           └── ulille
│               └── iut
│                   └── tva
│                       ├── DebugMapper.java
│                       ├── dto
│                       ├── Main.java
│                       ├── ressource
│                       │   └── TvaRessource.java
│                       └── service
│                           ├── CalculTva.java
│                           └── TauxTva.java
└── test
    └── java
        └── fr
            └── ulille
                └── iut
                    └── tva
~~~

Pour ce TP, nous n'utiliserons pas l'arborescence de tests (ça sera pour la prochaine fois :-)). Il n'y aura pas de base de données à gérer afin de pouvoir nous concentrer sur la mise ne place d'une ressource REST.

Le service que nous allons exposer sous forme de ressource REST permet de faire des calculs de TVA. La définition des différents taux se trouve dans la classe [`TauxTva`](src/main/java/fr/ulille/iut/tva/service/TauxTva.java) et les différents calculs possibles dans la classe [`CalculTva`](src/main/java/fr/ulille/iut/tva/service/CalculTva.java).

Le serveur Web qui hébergera notre ressource est lancé directement dans la classe [`Main`](src/main/java/fr/ulille/iut/tva/Main.java). Cette classe met également en place l'environnement Jersey qui va rechercher dans les paquetages définis les ressources disponibles.

Le développement de la ressource se fera dans la classe [`TvaRessource`](src/main/java/fr/ulille/iut/tva/ressource/TvaRessource.java).

## Développement de la ressources

### Une première personnalisation
Pour l'instant, les ressources que nous allons développer seront disponibles à partir de l'URI suivante : `http://localhost:8080/myapp/`. Modifiez la classe `Main` de manière à ce que l'URI utilisée soit `http://localhost:8080/api/v1` correspondant à notre première version de l'API (Pour en savoir plus sur la façon de gérer les changements de version d'une API REST, vous pouvez consulter cet [aticle](https://medium.com/neoxia/rest-api-design-les-best-practices-conseill%C3%A9es-par-neoxia-1442e99d8671).

Profiter en pour lire les commentaires dans le code de cette classe. Cela pourra vous servir plus tard...

### La première méthode

#### Implémentation
Nous allons éditer la classe [`TvaRessource`](src/main/java/fr/ulille/iut/tva/ressource/TvaRessource.java). Cette ressource devra être accessible via l'URI suivante : `http://localhost:8080/api/v1/tva`. Pour cela, vous devez annoter la classe avec [`@Path`](https://eclipse-ee4j.github.io/jaxrs-api/apidocs/3.0.0/jakarta/ws/rs/Path.html) :

~~~java
@Path("tva")
public class TvaRessource {

}
~~~

Une classe annotée avec `@Path` sera reconnue automatiquement comme une ressource REST par Jersey. Le chemin indiqué ici est relatif, il sera combiné avec l'URI définie dans la classe `Main`.

Nous allons pouvoir fournir dans cette classe une première méthode Java accessible via une requête HTTP GET. Nous utiliserons pour cela l'annotation [@GET]()

~~~java
@GET
@Path("tauxpardefaut")
public float getValeurTauxParDefaut() {
        return TauxTva.NORMAL.taux;
}
~~~

#### Test
Pour tester notre ressource, nous allons utiliser Maven pour compiler et lancer le serveur avec la commande `mvn compile exec:java` dans un terminal.

Dans un autre terminal, utilisez curl pour accéder à votre ressource et tester cette nouvelle méthode.

Vous devriez obtenir une réponse de ce type : 

~~~
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 4

20.0
~~~

On peut remarquer que comme votre code a renvoyé un résultat sans lever d'erreur, Jersey a automatiquement :
  - renvoyé le statut `200 OK`;
  - choisi le type MIME le plus adapté pour le résultat renvoyé dans le corps de la réponse : `Content-Type: text/plain`;
  - mis dans le corps de la réponse le résultat de votre méthode.

### On joue avec les paramètres de requête
La requête HTTP peut varier selon le chemin de l'URI ([@PathParam](https://eclipse-ee4j.github.io/jaxrs-api/apidocs/3.0.0/jakarta/ws/rs/PathParam.html)) ou les paramètres de requête ([@QueryParam](https://eclipse-ee4j.github.io/jaxrs-api/apidocs/3.0.0/jakarta/ws/rs/QueryParam.html))

La méthode ci-dessous renvoie la valeur du taux pour un niveau de TVA donné. Ce niveau de TVA (REDUIT, NORMAL, etc.) constitue une partie variable de l'URI qui sera notée entre `{}`. Le paramètre de la méthode est associé à cette partie du chemin grâce à l'annotation `@PathParam`.

~~~java
@GET
@Path("valeur/{taux}")
public float getValeurTaux(@PathParam("taux") String taux) {
  return TauxTva.valueOf(taux.toUpperCase()).taux;
}
~~~

Ajoutez cette méthode à votre classe puis testez la avec `curl`.