Merge branch 'doc_poo' into next_version

.gitlab-ci.yml

@@ -13,6 +13,7 @@ deploy-gtf-fr-documentation-dev :
     # - pip install sphinx-markdown-parser
     # - pip install myst-parser
     # - pip install pymdown-extensions
+    - pip install sphinxcontrib-phpdomain
     - sphinx-build -b html source build
     - aws s3 cp build/ s3://$S3_BUCKET_NAME_DEV_fr/ --recursive
   tags:

README.md

@@ -10,6 +10,7 @@ pip install sphinx_rtd_theme==0.5.2
 pip install sphinx-markdown-parser
 pip install myst-parser
 pip install pymdown-extensions
+pip install sphinxcontrib-phpdomain
 sphinx-build -b html source build
 ```
 

source/concept/index.rst

-Documentation Veremes sur les notions théoriques
+Notions théoriques
 ================================================
 
 .. image:: /images/Veremes_Black.svg
@@ -15,3 +15,4 @@ Documentation Veremes sur les notions théoriques
 
    system/index.rst
    bdd/index.rst
+   poo/index.rst
\ No newline at end of file

source/concept/poo/index.rst

+Programmation orienté objets
+============================================
+
+
+Nous allons parler ici de conceptes de programmation. 
+
+A quoi ça sert, pourquoi l'utiliser, comment ça fonctionne ?
+
+============================================
+
+.. toctree::
+   :maxdepth: 2
+
+   general.md
\ No newline at end of file

source/concept/rest/general.md

+# Introduction
+
+## Qu'est ce qu'une API ?
+
+En réalité, l’API ou Application Program Interface est, comme son nom l’indique, une interface servant à communiquer entre deux ou plusieurs applications (appareils, services, etc.) distinctes. Elle permet d’effectuer une requête spécifique et de recevoir une réponse, formulée sous un format établi.
+
+Elle se base donc sur une architecture client-serveur, sur laquelle le client est celui qui effectue la demande et le serveur, celui qui traite et renvoie la réponse. Le client n’a pas à se soucier de la manière dont ce traitement est fait, mais récupère juste ce qu’il a demandé. Le programme du côté du serveur peut donc être élaboré et écrit en n’importe quel langage. Cela n’affectera pas la réponse obtenue par le client, et ce, quelles que soient les technologies utilisées par celui-ci. Il suffit que ces technologies puissent interpréter le résultat communiqué et le tour est joué.
+
+Grâce à cette interface, les développeurs diminuent le volume de code à produire en n’effectuant que les liens entre les différentes APIs nécessaires pour leurs programmes et adaptés à leurs besoins et à ceux de l’entreprise.
+
+Les API permettent également de réutiliser à mainte reprise la même ressource, ce qui offre une flexibilité importante à chaque ressource.
+
+## Qu'est ce qu'une API REST ? 
+
+Le mot REST est l’abréviation de Representational State Transfer. Une API est dite RESTful lorsqu’elle répond à certaines contraintes architecturales. En gros, c’est un ensemble de règles à respecter afin de rendre l’interaction entre le client et le serveur le plus flexible, le plus simple et le plus rapide possible. C’est pour cela que les entreprises la préfèrent aux autres manières de faire appel à des APIs.
+
+Elle se base essentiellement sur le protocole HTTP pour l’envoi de requêtes relatives au CRUD (création, récupération, modification ou suppression). L’interaction avec les ressources basées sur un serveur s’effectue à partir d’un URI. 
+
+Il existe plusieurs formats dans lesquels ces dernières peuvent être retournées, à savoir : JSON, XML, XLT, YAML ou HTML.
+
+Le rôle premier d’une API REST est de servir d’intermédiaire entre le client et le serveur. C’est-à-dire que c’est elle qui réceptionne les requêtes émises par le client, le transmet à l’entité demandée au serveur, prend les réponses données par ce dernier puis les retransmettent au client.
+
+![archi_api](./images/archi-api.png)
+
+## Principes clés
+
+### L'URI comme identifiant de la ressource
+
+L'URI (ou le endpoint) permet d'identifier clairement un ressources.
+
+Exemple : **/rest/vx/clients** Permet d'agir sur la ressource gérant les clients.
+
+L'URI permet également de percevoir les relation entre les objets.
+
+Exemple : **/rest/vx/clients/{id}/commandes** Permet d'agir sur la ressource gérant les commandes d'un client spécifique.
+
+### Les verbes HTTP Pour identifier les opérations
+
+La seconde règle d’une architecture REST est d’utiliser les verbes HTTP existants plutôt que d’inclure l’opération dans l’URI de la ressource. Ainsi, généralement pour une ressource, il y a 4 opérations possibles (CRUD) :
+
+- Créer (create)
+- Afficher (read)
+- Mettre à jour (update)
+- Supprimer (delete)
+
+HTTP propose les verbes correspondant :
+
+- Créer (create) => POST
+- Afficher (read) => GET
+- Mettre à jour (update) => PUT
+- Supprimer (delete) => DELETE
+
+### Les réponses HTTP comme représentation de la ressource
+
+Il est important d’avoir à l’esprit que la réponse envoyée n’est pas une ressource, c’est la représentation d’une ressource. Ainsi, une ressource peut avoir plusieurs représentations dans des formats divers : HTML, XML, CSV, JSON, etc.
+
+C’est au client de définir quel format de réponse il souhaite reçevoir via l’entêteAccept. Il est possible de définir plusieurs formats.
+
+### L'utilisation du header authorization pour le jeton de connexion
+
+ il est primordial de sécuriser une API REST. En effet, nous ne sommes jamais à l’abri d’une personne malveillante souhaitant dérober des données que nous exposons, surtout à travers le web. Plusieurs manières sont envisageables et à mettre en place pour qu’une API soit le moins vulnérable possible :
+
+- Utiliser le protocole HTTPS permet de chiffrer les échanges entre les deux parties, à savoir le client et le serveur ;
+- Mettre en place un système d’authentification limite les personnes pouvant échanger avec l’API. Vous pouvez pour cela utiliser, par exemple, Json Web Token (JWT). JWT sert à identifier un utilisateur et à lui donner l’accès à l’API sur une durée déterminée. OAuth2 est également un excellent moyen d’authentifier un client pour lui prodiguer les autorisations nécessaires pour la consommation de l’API.
+- Utiliser une clé d’API ainsi qu’une clé secrète permet de reconnaitre les applications accédant à l’API. Cela permet également de signer les requêtes effectuées par celles-ci.
+
+## REST vs SOAP
+
+La première raison pour laquelle ces deux APIs sont comparées est sans doute que pendant très longtemps, avant l’apparition de l’API REST, SOAP a été la référence en termes d’utilisation des interfaces. En effet, ayant vu le jour en 1998, c’est un protocole se basant sur XML permettant d’interagir avec de nombreuses sortes d’autres protocoles tels que HTTP, UDP, TCP, etc.
+
+Cependant, malgré cette puissance qu’il détient, SOAP a tendance à occuper plus de bande passante et par conséquent de devenir assez lent. De plus, il nécessite l’apprentissage du XML et une certaine coordination entre le concepteur du code client et serveur afin d’éviter les erreurs qui peuvent être fatales pour chacun d’eux. Il n’est donc pas assez flexible pour que les applications actuelles puissent évoluer.
+
+C’est à cause de tout cela que, de nos jours, la plupart des développeurs privilégient l’utilisation d’une API RESTful.
+
+# Conception d'une API REST
+
+## Ressources
+
+La première étape consiste à identifier les ressources exploitables à travers l'API et comment elles sont exploitables.
+
+Cette étape est à mettre en lien avec les droits sur la Base de données ou les droits sur le système de fichier.
+
+## Endpoint et opération
+
+Il faut ensuite définir les endpoints, c'est à dire les ressources et les relations à mettre en place, à partir de là les endpoint devrait apparaitre de manière trés simple.
+
+Les opérations seront quant à elles le prolongement direct des droits sur votre base de onnées pour chacune des ressources.
+
+## Requêtes 
+
+Reste à mettre en place les contraintes techniques lié au développement d'un API REST : 
+
+- Format consommable en entrée : 
+  - Query parameters
+  - Headers
+  - Content-type acceptables en entrée
+- Format de donnée délivrable en sortie
+- Authentification
+- Headers de sécurité
+
+# Spécificité d'une API Vitis
+
+L'API PHP de Vitis va vous permettre de définir vos ressources et des les rendre exploitables facilement.
+
+Au niveau des spécificté s des requêtes : 
+- En entrée sont pris en compte 
+  - les query parameters
+  - Les body dont le content-type est de type 
+    - Multipart/Form-data
+    - application/x-www-urlencode
+    - application/json
+- Le header accpet permet de définir le format de récupération de la donnée, deux valeur possible : 
+  - application/json
+  - application/xml
+- Un token JWE ou systéme custom équivalent est utilisé pour gérer l'authentification.
+
+
+Une bonne partie de la sécurité est géré en flux commun avant l'arrivée dans votre code.
+
+Le tout s'appuyant sur le framework Symfony.
\ No newline at end of file

source/concept/rest/index.rst

+API REST
+============================================
+
+
+Nous allons parler ici de la conception d'une API REST. 
+
+A quoi ça sert, pourquoi l'utiliser, comment ça fonctionne ?
+
+============================================
+
+.. toctree::
+   :maxdepth: 2
+
+   general.md
\ No newline at end of file

source/conf.py

@@ -3,6 +3,8 @@ import os
 from sphinx_markdown_parser.parser import MarkdownParser
 from datetime import datetime
 #from recommonmark.transform import AutoStructify
+from sphinx.highlighting import lexers
+from pygments.lexers.web import PhpLexer
 
 source_parsers = {
     '.md': 'CommonMarkParser',
@@ -139,3 +141,8 @@ html_theme_options = {
     'includehidden': True,
     'titles_only': False
 }
+
+
+lexers['php'] = PhpLexer(startinline=True, linenos=1)
+lexers['php-annotations'] = PhpLexer(startinline=True, linenos=1)
+primary_domain = 'php'
\ No newline at end of file

source/dev-vitis/index.rst

-Documentation Veremes sur les méthodes de développement internes
+Méthodes de développement internes
 ================================================================
 
 .. image:: /images/Veremes_Black.svg

source/exploitation/index.rst

-Documentation Veremes sur les prrocédures d'exploitation
+Procédures d'exploitation
 =============================================
 
 .. image:: /images/Veremes_Black.svg

source/tools/index.rst

-Documentation Veremes sur les outils utilisés
+Outils utilisés
 =============================================
 
 .. image:: /images/Veremes_Black.svg